gRPC proto3语法指南

1. 定义一个消息类型

首先让我们来看一个非常简单的例子。假定我们有这样的需求，我们要定义一个搜索请求消息，每个消息都包含一个查询字符串，和你感兴趣的特定页面编号，以及每个页面的命中个数。

syntax = "proto3";

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

文件的第一行指定了你使用的是proto3的语法：如果你不指定，protocol buffer 编译器就会认为你使用的是proto2的语法。这个语句必须出现在.proto文件的非空非注释的第一行。

2. 指定字段类型

在上述例子中，所有的字段都是值类型：两个整形(page_number and result_per_page) 和一个字符串 (query)。然而，你也可以指定你的字段的组合类型，包括枚举和其他消息类型。

3. 分配标识——tag

如你所见，消息中的每个字段都有一个唯一的数字标识。这些标识用来在消息的二进制格式中识别你的字段，并且，一旦你的消息投入使用，这些标识就不应该再被修改。

注意，标识是由1到15使用一个字节来编码，包括标识数字和字段类型（你可以在Protocol Buffer 编码中查看更多详细）。

标识16到2047占用两个字节。所以你应该保留1到15，用作出现最频繁的消息类型的标识。记得为将来会继续增加并可能频繁出现的元素留一点儿标识区间，也就是说，不要一下子把1--15全部用完，为将来留一点儿哦。

你可以指定的最小的标识数字是1，最大是228，或者536,870,911。你也不能使用19000 到 19999之间的数字(FieldDescriptor::kFirstReservedNumber through FieldDescriptor::kLastReservedNumber)，因为它们被Protocol Buffers保留使用——如果你在自己的.proto文件中使用了一个保留数字，protocol buffer 编译器将会提示。同样的，你不能使用任何之前保留的标识。

4. 指定字段规则

消息字段可以是下边中的一种：

1. singular(单个): 符合语法规则的消息包含零个或者一个这样的字段（最多一个）。

2. repeated(重复)： 一个字段在合法的消息中可以重复出现一定次数（包括零次）。重复出现的值的次序将被保留。在proto3中，重复出现的值类型字段默认采用压缩编码。你可以在这里找到更多关于压缩编码的东西： Protocol Buffer Encoding。

5. 添加更多消息类型

多个消息类型可以定义在一个.proto文件中。这个在你定义多个关联的消息的时候非常有用，——这样，举个例子吧，如果你想定义你的搜索消息类型的响应消息格式，你可以在同一个.proto文件中添加如下的内容：

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

message SearchResponse {
 ...
}

6. 添加注释

在你的 .proto 文件中添加注释, 使用C/C++-风格的 // 语法，像下边这样：

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.
}

---

https://blog.csdn.net/lyjshen/article/details/52298003