书写 .proto 文件规范

使用 proto3 需要在 .proto 文件的最开始添加声明： syntax = "proto3"; 否则将按照 proto2 来编译。

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

消息解析时，如果不包含特定的字段，会用该字段的默认值代替。不同的类型，默认值不同：

• 字符串，默认为空字符串
• 字节，默认为空字节
• 布尔值，默认为 false
• 数值类型，默认为 0
• 枚举类型，默认是第一个定义的枚举项，必须为 0
• 对于 message 字段，默认值取决于具体的编程语言

repeated 字段的默认值为空（通常为对应编程语言的空列表）。

对于标量类型，一旦消息解析之后，无法判断该值是默认值还是未被设置的值。在设计时应该明确这一点，避免产生与设想不符的行为。

如下定义：

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
  enum Corpus {
    UNIVERSAL = 0;
    WEB = 1;
    IMAGES = 2;
    LOCAL = 3;
    NEWS = 4;
    PRODUCTS = 5;
    VIDEO = 6;
  }
  Corpus corpus = 4;
}

每个枚举定义 必须 将第一个元素的值设置为常量 0 。因为：

• 必须要有一个零值，来保证数值类型有默认值
• 零值必须是第一个元素，为了跟 proto2 兼容

通过设置 allow_alias=true ，你可以定义相同的值分配给不同的枚举常量，否则出现相同的值编译不通过：

message MyMessage1 {
  enum EnumAllowingAlias {
    option allow_alias = true;
    UNKNOWN = 0;
    STARTED = 1;
    RUNNING = 1;
  }
}

枚举的值必须在 32-bit 整型范围内，不建议使用复数，编码效率不高。你可以在消息的内部、外部定义枚举。还可以使用 MessageType.EnumType 添加声明，将消息中的枚举类型公开。

你可以使用已经定义的消息类型作为另外一个消息的字段类型。如：

message SearchResponse {
  repeated Result results = 1;
}

message Result {
  string url = 1;
  string title = 2;
  repeated string snippets = 3;
}

你可以在消息类型中定义和使用消息类型，如下：

message SearchResponse {
  message Result {
    string url = 1;
    string title = 2;
    repeated string snippets = 3;
  }
  repeated Result results = 1;
}

如果想要在父消息外面使用内部定义的消息，需要加一层引用，如 Parent.Type ：

message SomeOtherMessage {
  SearchResponse.Result result = 1;
}

消息定义可以内嵌很多层。

如果一个已经存在的消息类型不再能满足需求，比如，添加额外的字段等。在不破坏现有的消息类型更新非常简单，但是要遵守一下规则：

• 不要更改现有的任何字段的字段编号。
• 添加新字段时，老的消息格式序列化仍旧可以被新的解析，新的字段会以默认值出现。同样新的消息格式序列化也可以被旧的解析，但是会忽略新字段。 兼容性
• 删除字段时，要保证新的字段编号不与删除的相同。重命名该字段，或者添加 OBSOLETE_ 前缀，或者使用 reserved 关键字。 以确保将来的用户不会复用之前的字段编号。
• int32 uint32 int64 uint64 和 bool 都是兼容的 - 也就是说你可以再它们之间修改字段的类型，而不会破坏向前或者向后兼容性。 如果解析中的字段类型不同，会发生自动类型转换。如果字节数变少了，会自动截断。
• sint32 和 sint64 相互兼容，但与其它类型不兼容。
• string 和 bytes 只要是有效的 UTF-8 ，相互兼容。
• 如果字节包含消息的编码版本，则 bytes 和内嵌消息兼容。
• fixed32 跟 sfixed32 兼容， fixed64 和 sfixed64 兼容。
• enum 和 int32 uint32 int64 uint64 兼容（如果值不同，自动截断）。但要注意，反序列化消息时，客户端代码可能会以不同的方式对待它们： 比如，无法识别的 proto3 enum 类型会保留在消息中，在反序列化消息时如何表达取决于具体的语言。 int 字段只是保留其值。
• Changing a single value into a member of a new oneof is safe and binary compatible. Moving multiple fields into a new oneof may be safe if you are sure that no code sets more than one at a time. Moving any fields into an existing oneof is not safe.

未知(Unknown)的字段表示在序列化话数据时，解析器无法识别的字段。比如说，用旧的二进制数据使用新的二进制解析时，新的字段变成旧二进制数据中的未知字段。

原本，proto3 消息在解析过程中会始终丢弃未知字段，但是 3.5 版本之后，我们重新引入和保留未知字段以匹配 proto2 行为的功能。 在 3.5 或者更高版本中，未知字段将在解析期间保留并包含在序列化输出中。

Any 消息类型可以作为嵌入类型，而无须定义。 Any 以 bytes 为单位，包含任何序列化消息，扮演着该消息类型的全局唯一标识符的 URL。 要使用 Any 类型，需要先导入 google/protobuf/any.proto 。

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  repeated google.protobuf.Any details = 2;
}

给定类型默认的 URL 是 type.googleapis.com/packagename.messagename 。

不同语言的实现会在运行时库帮助下以类型安全的方式 pack 和 unpack Any 值。比如，在 Java 中，Any 类型用特殊的 pack() 和 unpack() 存取器， C++ 是 PackForm() 和 UnpackTo() 方法。

当前用于 Any 类型的运行时库正在开发中。

如果一个消息有很多的字段，但是在同一个时间内只会被设置其中的一个，你可以使用 oneof 特性来实现它，以节省内存。

Oneof 除了所有的字段共享一块内存之外的行为和其它的普通字段一样，最多可以同时设置一个字段，设置 oneof 中的任何一个字段会清空其它的成员。 你可以使用特殊的 case() 或者 WhichOneof() 方法来判断设置了哪个值，具体依赖于你选择语言的实现。

如果想要在数据定义中创建关联映射，protobuf 提供了方便的快捷语法：

map<key_type, value_type> map_field = N;

key_type 可以使用任何整型和字符串类型（也就是说除了标量类型浮点型和 bytes 之外的）。枚举不是一个有效的 key_type ， value_type 可以是除了 map 以外的所有类型。

使用注意：

• Map 字段不可以是 repeated 。 字段不可以，不是 value 不可以
• Map 的 key 和 value 顺序是不确定的，因为你不可以依赖与 map 中的元素的特定顺序。
• 当生成 .proto 的文本格式时，maps 是按 key 排序，数值类型的 key 是按照数值排序。
• 编码的时候重复的键会使用最后一个看到的值。解码的时候，出现相同的 keys 会解码失败。
• 如果提供了一个 key 但是没有值，序列化行为取决于语言。C++，Java，Python 会使用类型的默认值，其它的语言什么都不做。

你可以在 .proto 文件中添加一个可选的 package 指示符用来放置协议消息类型质检的命名冲突。

package foo.bar;
message Open { ... }

然后你可以在另外的消息定义中使用：

message Foo {
  ...
  foo.bar.Open open = 1;
  ...
}

package 不同的语言生成的代码不同：

• C++ 等价于 namespace。
• Python 会被路忽略，因为 Python 的模块是根据它在文件系统中的位置进行组织的。
• Go 当做 Go 的 package 名称，除非你显式的提供了 option go_package 。

如果你要与 RPC 系统一起使用你的消息类型，你可以在 .proto 文件中定义一个 RPC 服务接口，protobuf 编译器会根据你选择的语言自动生成服务接口代码和存根。

如下，一个 RPC 服务请求是 SearchRequest 消息，返回是 SearchResponse 消息，你可以这样定义：

service SearchService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

与 protobuf 一起使用的直接使用 RPC 系统是 gRPC：谷歌开发的一个语言和平台无关的开源的 RPC 系统。gRPC 和 protobuf 是最佳搭档， 使用特殊的编译插件可以直接生成相关的 RPC 代码。

在 这里 列出了很多第三方的 protobuf 插件。

Proto3 支持 JSON 编码规范，这使得在系统之间共享数据更加容易。

https://developers.google.com/protocol-buffers/docs/proto3#json

.proto 文件中的各种声明可以使用许多的 options 来注释。Options 不会改变声明的整体定义，但可能会影响在特定上下文中处理声明的方式。 可用的 Options 的完整定义在 google/protobuf/descriptor.proto 中。

• 一些 options 是在文件级别定义，这意味着它们在顶层范围定义，而不是在任何的消息、枚举或者服务定义中。
• 一些 options 是在消息级别定义，意味着它们应该写在消息内部定义中。
• 一些 options 是字段级别的选项，它们应该写在字段定义上。

Options 可以写在枚举类型、枚举值、oneof 字段，服务类型和服务方法；但是目前没有有用的 options 给它们用。

下面是常用的选项：

• java_package
• java_multiple_files
• java_outer_classname
• optimize_for
• cc_enable_arenas
• objc_class_prefix

• deprecated 字段选项，如果设置为 true ，表示该字段的已经不推荐使用，不应该在新的代码中使用。在大多数语言中，都不会有实际的效果。 Java 中，会添加 @Deprecated 注解。如果一个字段没被用过，但是不想新用户使用它，可以使用 reserved 声明，而不是 deprecated。

  int32 old_field = 6 [deprecated = true];