Protobuf语法

1、基本规范

• 文件以.proto做为文件后缀，除结构定义外的语句以分号结尾
• 结构定义可以包含：message、service、enum
• rpc方法定义结尾的分号可有可无
• Message命名采用驼峰命名方式，字段命名采用小写字母加下划线分隔方式

  message SongServerRequest {
      required string song_name = 1;
  }

• Enums类型名采用驼峰命名方式，字段命名采用大写字母加下划线分隔方式

  enum Foo {
      FIRST_VALUE = 1;
      SECOND_VALUE = 2;
  }

• Service与rpc方法名统一采用驼峰式命名

2、字段规则

字段格式：限定修饰符 | 数据类型 | 字段名称 | = | 字段编码值 | [字段默认值]

• 限定修饰符包含 required\optional\repeated

  • Required: 表示是一个必须字段，必须相对于发送方，在发送消息之前必须设置该字段的值，对于接收方，必须能够识别该字段的意思。发送之前没有设置required字段或者无法识别required字段都会引发编解码异常，导致消息被丢弃

  • Optional：表示是一个可选字段，可选对于发送方，在发送消息时，可以有选择性的设置或者不设置该字段的值。对于接收方，如果能够识别可选字段就进行相应的处理，如果无法识别，则忽略该字段，消息中的其它字段正常处理。—因为optional字段的特性，很多接口在升级版本中都把后来添加的字段都统一的设置为optional字段，这样老的版本无需升级程序也可以正常的与新的软件进行通信，只不过新的字段无法识别而已，因为并不是每个节点都需要新的功能，因此可以做到按需升级和平滑过渡

  • Repeated：表示该字段可以包含0~N个元素。其特性和optional一样，但是每一次可以包含多个值。可以看作是在传递一个数组的值

• 数据类型

  • Protobuf定义了一套基本数据类型。几乎都可以映射到C++\Java等语言的基础数据类型
    

  + N 表示打包的字节并不是固定。而是根据数据的大小或者长度
  + 关于 fixed32 和int32的区别。
    fixed32的打包效率比int32的效率高，但是使用的空间一般比int32多。
    因此一个属于时间效率高，一个属于空间效率高

• 字段名称

  • 字段名称的命名与C、C++、Java等语言的变量命名方式几乎是相同的
  • protobuf建议字段的命名采用以下划线分割的驼峰式。例如 first_name 而不是firstName

• 字段编码值

  • 有了该值，通信双方才能互相识别对方的字段，相同的编码值，其限定修饰符和数据类型必须相同，编码值的取值范围为 1~2^32（4294967296）

  • 其中 1~15的编码时间和空间效率都是最高的，编码值越大，其编码的时间和空间效率就越低，所以建议把经常要传递的值把其字段编码设置为1-15之间的值

  • 1900~2000编码值为Google protobuf 系统内部保留值，建议不要在自己的项目中使用

• 字段默认值

  • 当在传递数据时，对于required数据类型，如果用户没有设置值，则使用默认值传递到对端

3、service如何定义

• 如果想要将消息类型用在RPC系统中，可以在.proto文件中定义一个RPC服务接口，protocol buffer编译器会根据所选择的不同语言生成服务接口代码

• 例如，想要定义一个RPC服务并具有一个方法，该方法接收SearchRequest并返回一个SearchResponse，此时可以在.proto文件中进行如下定义：

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

• 生成的接口代码作为客户端与服务端的约定，服务端必须实现定义的所有接口方法，客户端直接调用同名方法向服务端发起请求，比较麻烦的是，即便业务上不需要参数也必须指定一个请求消息，一般会定义一个空message