python proto生成pb文件 protobuf python api

转载

恋上一只猪 2024-07-19 15:50:05

文章标签 python proto生成pb文件 golang API Go 文章分类 Python 后端开发

前言

作者：Joe Tsai, Damien Neil 和 Herbie Ong

我们很高兴地宣布，用于 Google 的语言无关数据交换格式 protocol buffers¹

新 API 的动机

Go 的第一个 protocol buffer 绑定由 Rob Pike 于 2010 年 3 月宣布²。两年后 Go1 才发布。

自从首次发布以来的十年中，该包与 Go 一起发展壮大。它的用户需求也有所增长。

许多人想编写使用反射来检查 protocol buffer 的程序。反射包³提供了 Go 类型和值的视图，但是忽略了 protocol buffer 类型系统中的信息。例如，我们可能想编写一个遍历日志条目并清除任何注解（annotation）为包含敏感数据的字段的函数。注解不是 Go 类型系统的一部分。

另一个常见的需求是使用 protocol buffer 编译器生成的数据结构之外的其他数据结构，例如能够代表其消息类型在编译时未知的动态消息类型。

我们还观察到，常见的问题根源是 proto.Message⁴

以上这三个问题都有一个共同的原因，并且有一个共同的解决方案：Message 接口应完全指定消息的行为，并且对 Message 值进行操作的函数应自由接受可以正确实现该接口的任何类型。

由于在保持包 API 兼容的同时无法更改 Message 类型的现有定义，因此我们决定是时候开始研究 protobuf 模块的新的，不兼容的主要版本了。

今天，我们很高兴发布该新模块。我们希望您能喜欢。

反射

反射是新实现的旗舰特性。类似于 reflect 包如何提供 Go 类型和值的视图， google.golang.org/protobuf/reflect/protoreflect⁵

对 protoreflect 包的完整描述对于这篇文章来说可能会花很长时间，但是让我们看一下如何编写我们前面提到的 log-scrubbing 函数。

首先，我们将编写一个 .proto 文件，该文件定义 google.protobuf.FieldOptions⁶

syntax = "proto3";
import "google/protobuf/descriptor.proto";
package golang.example.policy;
extend google.protobuf.FieldOptions {
    bool non_sensitive = 50000;
}

我们可以使用此选项将某些字段标记为不敏感。

message MyMessage {
    string public_name = 1 [(golang.example.policy.non_sensitive) = true];
}

接下来，我们将编写一个 Go 函数，该函数接受任意消息值并删除所有敏感字段。

// Redact clears every sensitive field in pb.
func Redact(pb proto.Message) {
   // ...
}

此函数接受 proto.Message⁷，这是由所有生成的消息类型实现的接口类型。此类型是 protoreflect 包中定义的别名：

type ProtoMessage interface{
    ProtoReflect() Message
}

为了避免填充所生成消息的名称空间，该接口仅包含一个返回 protoreflect.Message⁸

（为什么要使用别名？因为 protoreflect.Message 具有返回原始 proto.Message 的相应方法，所以我们需要避免两个包之间的循环导入。）

protoreflect.Message.Range⁹

m := pb.ProtoReflect()
m.Range(func(fd protoreflect.FieldDescriptor, v protoreflect.Value) bool {
    // ...
    return true
})

使用描述字段的 protocol buffer 类型的 protoreflect.FieldDescriptor¹⁰ 和包含字段值的 protoreflect.Value¹¹

protoreflect.FieldDescriptor.Options¹²

opts := fd.Options().(*descriptorpb.FieldOptions)

（为什么要使用类型断言？由于生成的描述符 pb 包依赖于 protoreflect，因此 protoreflect 包不能在不引起循环导入的情况下返回具体的选项类型。）

然后，我们可以检查选项以查看扩展布尔值：

if proto.GetExtension(opts, policypb.E_NonSensitive).(bool) {
    return true // don't redact non-sensitive fields
}

请注意，我们在这里查看的是字段描述符，而不是字段值。我们感兴趣的信息在于 protocol buffer 类型系统，而不是 Go 语言。

这也是我们简化了 proto 包 API 的一个示例。原来的 proto.GetExtension¹³ 返回一个值和一个错误。新的proto.GetExtension¹⁴

一旦我们确定了需要修改的字段，将其清除很简单：

m.Clear(fd)

综上所述，我们完整的修改功能是：

// Redact clears every sensitive field in pb.
func Redact(pb proto.Message) {
    m := pb.ProtoReflect()
    m.Range(func(fd protoreflect.FieldDescriptor, v protoreflect.Value) bool {
        opts := fd.Options().(*descriptorpb.FieldOptions)
        if proto.GetExtension(opts, policypb.E_NonSensitive).(bool) {
            return true
        }
        m.Clear(fd)
        return true
    })
}

更完整的实现可以递归地深入消息值字段。我们希望这个简单的例子能使您了解 protocol buffer 反射及其用法。

版本号

我们将 Go protocol buffers 的原始版本称为 APIv1，将新版本称为 APIv2。由于 APIv2 与 APIv1 不向后兼容，因此我们需要为每个 APIv 使用不同的模块路径。

（这些 API 版本与 protocol buffers 语言的版本不同：proto1，proto2 和 proto3。APIv1 和 APIv2 是 Go 中的具体实现，均支持 proto2 和 proto3 语言版本。）

github.com/golang/protobuf¹⁵

google.golang.org/protobuf¹⁶

我们知道，并非所有用户都将以相同的速度迁移到包的新主版本。有些会快速切换；其他可能会无限期保留在旧版本中。即使在一个程序中，某些部分可能使用一个 API，而其他部分则使用另一个。因此，我们必须继续支持使用 APIv1 的程序。

github.com/golang/protobuf@v1.3.4 是 APIv1 最新 pre-APIv2 版本。
github.com/golang/protobuf@v1.4.0 是根据 APIv2 实现的 APIv1 版本。它的 API 相同，但是基础实现由新的实现支持。此版本包含在 APIv1 和 APIv2 proto.Message 接口之间转换的函数，以简化两者之间的过渡。
google.golang.org/protobuf@v1.20.0 是 APIv2。该模块依赖 github.com/golang/protobuf@v1.4.0，因此任何使用 APIv2 的程序都会自动选择与其集成的 APIv1 版本。
（为什么要从 v1.20.0 版本开始？为了清楚起见。我们认为 APIv1 不会达到 v1.20.0，因此仅版本号就应该足以区分 APIv1 和 APIv2。）

我们打算无限期地保持对 APIv1 的支持。

该组织确保任何给定程序都将仅使用单个 protocol buffer 实现，而不管其使用哪个 API 版本。它允许程序逐渐或根本不采用新的 API，同时仍获得新实现的优点。最小版本选择的原则意味着程序可以保留在旧的实现上，直到维护者选择更新到新的（直接或通过更新依赖项）。

值得关注的其他特性

google.golang.org/protobuf/encoding/protojson¹⁷

google.golang.org/protobuf/types/dynamicpb¹⁸

google.golang.org/protobuf/testing/protocmp¹⁹ 包提供了将 protocol buffer 消息与 github.com/google/cmp²⁰

google.golang.org/protobuf/compiler/protogen²¹

总结

google.golang.org/protobuf 模块是 Go 对 protocol buffers 支持的主要改进，它为反射，自定义消息实现和清理的 API surface 提供了优先支持。我们打算无限期地维护以前的 API 作为新 API 的包装，从而使用户可以按照自己的步调逐步采用新 API。

我们在此更新的目标是在解决旧 API 的缺点的同时，提升旧 API 的优势。完成新实现的每个组件后，我们将其在 Google 的代码库中投入使用。这种逐步推出的方式使我们对新 API 的可用性以及新实现的性能和正确性都充满信心。我们相信已经准备好用于生产环境了。

我们很兴奋地发布了该版本，并希望它将在未来十年甚至更长时间内为 Go 生态系统服务！

参考资料

protocol buffers: https://developers.google.com/protocol-buffers ↩︎
Rob Pike 于 2010 年 3 月宣布: https://blog.golang.org/third-party-libraries-goprotobuf-and ↩︎
反射包: http://docs.studygolang.com/pkg/reflect ↩︎
proto.Message: https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#Message ↩︎
google.golang.org/protobuf/reflect/protoreflect: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc ↩︎
google.protobuf.FieldOptions: https://github.com/protocolbuffers/protobuf/blob/b96241b1b716781f5bc4dc25e1ebb0003dfaba6a/src/google/protobuf/descriptor.proto#L509 ↩︎
proto.Message: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message ↩︎
protoreflect.Message: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message ↩︎
protoreflect.Message.Range: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message.Range ↩︎
protoreflect.FieldDescriptor: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#FieldDescriptor ↩︎
protoreflect.Value: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Value ↩︎
protoreflect.FieldDescriptor.Options: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Descriptor.Options ↩︎
proto.GetExtension: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension ↩︎
proto.GetExtension: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension ↩︎
github.com/golang/protobuf: https://pkg.go.dev/github.com/golang/protobuf?tab=overview ↩︎
google.golang.org/protobuf: https://pkg.go.dev/google.golang.org/protobuf?tab=overview ↩︎
google.golang.org/protobuf/encoding/protojson: https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson ↩︎
google.golang.org/protobuf/types/dynamicpb: https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb ↩︎
google.golang.org/protobuf/testing/protocmp: https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp ↩︎
github.com/google/cmp: https://pkg.go.dev/github.com/google/go-cmp/cmp ↩︎
google.golang.org/protobuf/compiler/protogen: https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen?tab=doc ↩︎