谷歌API 设计指南

使用 proto3

Preview

本章将讨论如何在 API 设计中使用 Protocol Buffers。 为了简化开发者体验并提高运行时效率,gRPC API 使用 Protocol Buffers 版本 3 (proto3) 进行 API 定义。 Protocol Buffers 是一种与语言和平台无关的简单接口定义语言 (IDL),用于定义数据结构模式和编程接口。它支持二进制和文本传输格式,并可在不同平台上与许多不同的线路协议结合使用。 Proto3 是 Protocol Buffers 的最新版本,包括对 proto2 的以下更改:

  • 对于原初字段,系统默认移除字段存在方法(也称为 hasField)。未设置的原初字段具有语言定义的默认值。
    • 消息字段的存在方法仍然可用,可以使用编译器生成的 hasField 方法进行测试,或者与 null 或由实现定义的 sentinel 值进行比较。
    • 从 protobuf v3.14 开始,基元字段可以使用 optional 关键字来区分默认值和未设置的值,但通常不建议这样做。
  • 用户定义的默认字段值不再可用。
  • 枚举定义必须从枚举值零开始。
  • 必填字段不再可用。
  • 扩展程序不再可用,请改用 google.protobuf.Any
    • 由于后向和运行时兼容性原因,特别准许使用 google/protobuf/descriptor.proto
  • 群组语法已被移除。

之所以移除这些功能,是为了使 API 设计更简单、更稳定、性能更高。例如,在记录消息之前通常需要过滤某些字段,例如移除敏感信息。如果这些字段是必填字段,则无法执行此操作。 如需了解详情,请参阅 Protocol Buffers