gRPC proto3语法指南

短命女 2022-02-19 15:23 290阅读 0赞

### 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][https_blog.csdn.net_lyjshen_article_details_52298003] #####

[https_blog.csdn.net_lyjshen_article_details_52298003]: https://blog.csdn.net/lyjshen/article/details/52298003