【proto3】定义 Message

定义一个 Message 类型

假设您要定义 search request message 格式，其中每个搜索请求都有一个查询字符串、您感兴趣的特定结果页面、每页的结果数量。
这是用于定义消息类型的 .proto 文件。

syntax = "proto3";

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

• 该文件的第一行指定您使用的是 proto3 语法：如果您不这样做，protocol buffer 编译器将假定您使用的是 proto2。 这必须是文件的第一个非空、非注释行。
• SearchRequest 消息定义指定了三个字段（名称/值对），每个字段用于您希望包含在此类消息中的每条数据。 每个字段都有一个名称和一个类型。

指定字段类型

在上面的示例中，所有字段都是标量类型：两个整数（page_number 和 result_per_page）和一个字符串（query）。
但是，您也可以为字段指定复合类型，包括枚举和其他消息类型。

分配字段编号

如您所见，消息定义中的每个字段都有一个唯一编号。 这些字段编号用于以消息二进制格式标识您的字段，一旦使用您的消息类型就不应更改。

请注意，1 到 15 范围内的字段编号需要一个字节进行编码，包括字段编号和字段类型（您可以在 Protocol Buffer Encoding 中找到更多相关信息）。
16 到 2047 范围内的字段编号占用两个字节。

因此，您应该为非常频繁出现的消息元素保留数字 1 到 15。 请记住为将来可能添加的频繁出现的元素留出一些空间。

可以指定的最小字段编号是 1，最大的是 2^29 - 1，即 536,870,911。
您也不能使用数字 19000 到 19999（FieldDescriptor::kFirstReservedNumber 到 FieldDescriptor::kLastReservedNumber），因为它们是为 protocol
buffer 实现保留的。如果您在 .proto 中使用这些保留数字之一，编译器会报错。 同样，您不能使用任何以前保留的字段编号。

指定字段规则

消息字段可以是以下之一：

• singular
  格式良好的 message 可以包含零个或一个此字段（但不超过一个）。
  这是 proto3 语法的默认字段规则。
• repeated
  格式良好的 message 中，此字段可以重复任意次数（包括零次）。
  重复值的顺序将被保留。

添加更多消息类型

可以在单个 .proto 文件中定义多种 message 类型。 如果您要定义多个相关message，这很有用。
例如，如果您想定义与您的 SearchResponse 消息类型，相对应的回复消息格式，您可以将其添加到同一个 .proto 中：

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

message SearchResponse {
 ...
}

添加注释

To add comments to your .proto files, use C/C++-style // and /* ... */ syntax.

/* SearchRequest represents a search query, with pagination options to
 * indicate which results to include in the response. */

message SearchRequest {
  string query = 1;
  int32 page_number = 2;  // Which page number do we want?
  int32 result_per_page = 3;  // Number of results to return per page.
}

保留字段

如果您通过 完全删除某个字段 或 将其注释掉 来更新消息类型，未来的用户可以在对类型进行自己的更新时重用该字段编号。
如果他们稍后加载相同 .proto 的旧版本，这可能会导致严重的问题，包括数据损坏、隐私错误等。
确保不会发生这种情况的一种方法是指定保留已删除字段的字段编号（和/或名称，这也可能导致 JSON 序列化问题）。
如果将来有任何用户尝试使用这些字段标识符，protocol buffer 编译器会抱怨。

message Foo {
 reserved 2, 15, 9 to 11;
 reserved "foo", "bar";
}

请注意，您不能在同一保留语句中混合字段名称和字段编号。

你的 .proto 生成了什么？

For Go, the compiler generates a .pb.go file with a type for each message type in your file.