Go 官宣:新版 Protobuf API（protocol version）

原文作者：Joe Tsai, Damien Neil 和 Herbie Ong

原文链接：
https://blog.golang.org/a-new-go-api-for-protocol-buffers

发布时间：2020-03-02

翻译：polaris，Go 语言中文网

简介

我们很高兴地宣布，用于 Google 的语言无关数据交换格式 protocol buffers[1] 的新版 Go API 发布了，这是一次重大的版本升级。

新 API 的动机

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

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

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

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

我们还观察到，常见的问题根源是 proto.Message[4] 接口，它标识生成的消息类型的值，对描述这些类型的行为几乎没有作用。当用户创建实现该接口的类型（通常通过在另一个结构中嵌入消息而无意间实现）并将这些类型的值传递给期望生成消息值的函数时，程序崩溃或行为异常。

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

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

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

反射

反射是新实现的旗舰特性。类似于 reflect 包如何提供 Go 类型和值的视图，
google.golang.org/protobuf/reflect/protoreflect[5] 包提供了根据 protocol buffer 类型系统的值视图。

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

首先，我们将编写一个 .proto 文件，该文件定义
google.protobuf.FieldOptions[6] 类型的扩展名，以便我们可以将字段注解为包含或不包含敏感信息。

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[7]，这是由所有生成的消息类型实现的接口类型。此类型是 protoreflect 包中定义的别名：

type ProtoMessage interface{
    ProtoReflect() Message
}

为了避免填充所生成消息的名称空间，该接口仅包含一个返回 protoreflect.Message[8]的方法，该方法提供对消息内容的访问。

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

protoreflect.Message.Range[9] 方法为消息中的每个填充字段调用一个函数。

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

使用描述字段的 protocol buffer 类型的
protoreflect.FieldDescriptor[10] 和包含字段值的 protoreflect.Value[11] 来调用 range 函数。

protoreflect.FieldDescriptor.Options[12] 方法以
google.protobuf.FieldOptions 消息的形式返回字段选项。

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[13] 返回一个值和一个错误。新的proto.GetExtension[14] 仅返回一个值，如果不存在该字段，则返回默认值。在 Unmarshal 时间时报告扩展解码错误。

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

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[15] 是模块 APIv1 版本。

google.golang.org/protobuf[16] 模块是 APIv2。我们利用了需要更改导入路径以切换到与特定托管服务提供商无关的路径的优势。（我们考虑了
google.golang.org/protobuf/v2，以明确说明这是该 API 的第二个主要版本，但从长远来看，选择较短的路径是更好的选择。）

我们知道，并非所有用户都将以相同的速度迁移到包的新主版本。有些会快速切换；其他可能会无限期保留在旧版本中。即使在一个程序中，某些部分可能使用一个 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[17] 包使用规范的 JSON 映射将 protocol buffer 消息与 JSON 相互转换，并解决了旧 jsonpb 包难以解决的许多问题，而这些问题不会对现有用户造成问题。

google.golang.org/protobuf/types/dynamicpb[18] 包为 protocol buffer 类型在运行时派生的消息提供了 proto.Message 的实现。

google.golang.org/protobuf/testing/protocmp[19] 包提供了将 protocol buffer 消息与 github.com/google/cmp[20] 包进行比较的功能。

google.golang.org/protobuf/compiler/protogen[21] 包提供了对编写协议编译器插件的支持。

总结

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

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

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

参考资料

[1]

protocol buffers: https://developers.google.com/protocol-buffers

[2]

Rob Pike 于 2010 年 3 月宣布:
https://blog.golang.org/third-party-libraries-goprotobuf-and

[3]

反射包:
http://docs.studygolang.com/pkg/reflect

[4]

proto.Message: https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#Message

[5]

google.golang.org/protobuf/reflect/protoreflect: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc

[6]

google.protobuf.FieldOptions: https://github.com/protocolbuffers/protobuf/blob/b96241b1b716781f5bc4dc25e1ebb0003dfaba6a/src/google/protobuf/descriptor.proto#L509

[7]

proto.Message: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message

[8]

protoreflect.Message: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message

[9]

protoreflect.Message.Range: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message.Range

[10]

protoreflect.FieldDescriptor: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#FieldDescriptor

[11]

protoreflect.Value: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Value

[12]

protoreflect.FieldDescriptor.Options: https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Descriptor.Options

[13]

proto.GetExtension: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension

[14]

proto.GetExtension: https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension

[15]

github.com/golang/protobuf: https://pkg.go.dev/github.com/golang/protobuf?tab=overview

[16]

google.golang.org/protobuf: https://pkg.go.dev/google.golang.org/protobuf?tab=overview

[17]

google.golang.org/protobuf/encoding/protojson: https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson

[18]

google.golang.org/protobuf/types/dynamicpb: https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb

[19]

google.golang.org/protobuf/testing/protocmp: https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp

[20]

github.com/google/cmp: https://pkg.go.dev/github.com/google/go-cmp/cmp

[21]

google.golang.org/protobuf/compiler/protogen: https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen?tab=doc