protobuf语法指南

1. 概述
前两篇文章，我们概括介绍《Google Protocol Buffers 概述》以及带领大家 简单的《Google Protocol Buffers 入门》，接下来，再稍微详细一点介绍 Protocol Buffers 书写语言。该篇文章主要讲解如何使用 PB 语言构建数据，包 括.proto 文件语法及如果使用.proto 文件生成数据存取类。 本篇主要包括：
? ? ? ? ? ? ?
定义一个 PB message 类型 介绍 PB 数据类型 Optional 字段及其默认值 枚举类型 使用其他 Message 类型作为 filed 类型 嵌套类型 更新 Message
2. 定义一个 PB message 类型
假如现在需要定义搜索请求的 message 格式，每条 message 包含三个字段： 搜索语句(query string)，需要的返回结果页数(page_number)，以及该页上 的结果数。可如下定义.proto 文件。 message SearchRequest { required string query = 1; optional int32 page_number = 2; optional int32 result_per_page = 3; } 该 message 定义声明三个字段(name/value pairs)，每个字段有一个名字和 类型。 2.1 声明字段类型 上例中，所有的字段类型均为标准类型：两个整型和一个字符串类型。当然，也 可以指定复合类型：枚举类型和其他自定义 message 类型。 2.2 给字段赋值数字标签 从上例中可以发现，message 中定义的每个字段都有一个唯一的数字标签。该 标签的作用是在二进制 message 中唯一标示该字段， 一旦定义该字段的值就不 能够再更改。有一点需要强调：1~15 的数字标签编码后仅占一个字节(byte)， 包括数字标签和字段类型。16~2047 的数字标签占两个字节(byte)。因此， 1~15 的数字标签应该用于最频繁出现的元素。设计时要考虑到不要一次用完 1~15 的标签，要考虑到将来也可能出现频繁出现的元素。

最小的数字标签是 1， 最大的数字标签是 2 的 29 次方-1， 也即 536,870,911。 但是并不是这之间所有的数字标签你都能用，例如 19000~19999。这个区间 的数字标签就像是 java 中的保留字一样，他们是 PB 的保留数字标签。如果该 区间的数字标签出现在.proto 文件中，PB 编译器会出错。 2.3 字段标示符 字段标示符有三个： message 的没一个字段，都要用如下的三个修饰符(modifier)来声明： 1. required： 必须赋值， 不能为空， 否则该条 message 会被认为是“uninitialized”。 build 一个“uninitialized” message 会抛出一个 RuntimeException 异常， 解析一条“uninitialized” message 会抛出一条 IOException 异常。 除此之外， “required”字段跟“optional”字段并无差别。 2. optional： 字段可以赋值， 也可以不赋值。 假如没有赋值的话， 会被赋上默认值。 对于简单类型，默认值可以自己设定，例如上例的 PhoneNumber 中的 PhoneType 字段。如果没有自行设定，会被赋上一个系统默认值，数字类型会 被赋为 0，String 类型会被赋为空字符串，bool 类型会被赋为 false。对于内 置的 message，默认值为该 message 的默认实例或者原型，即其内所有字段 均为设置。当获取没有显式设置值的 optional 字段的值时，就会返回该字段的 默认值。 3. repeated：该字段可以重复任意次数，包括 0 次。重复数据的顺序将会保存在 protocol buffer 中， 将这个字段想象成一个可以自动设置 size 的数组就可以了。 由于一些历史原因，数字类型的 repeated 字段性能有些不尽人意，但是，PB 已经做了改进，但是需要再添加一点改动，即在声明后添加[packed=true]例 如： repeated int32 samples = 4 [packed=true]; Notice：应该格外小心定义 Required 字段。当因为某原因要把 Required 字 段改为 Optional 字段是，会有问题，老版本读取器会认为消息中没有该字段不 完整， 可能会拒绝或者丢弃该字段(Google 文档是这么说的， 但是我试了一下， 将 required 的改为 optional 的，再用原来 required 时候的解析代码去读，如 果字段赋值的话， 并不会出错， 但是如果字段未赋值， 会报这样错误： Exception in thread “main” com.google.protobuf.InvalidProtocolBufferException: Message missing required fields:fieldname)。在设计时，尽量将这种验证 放在应用程序端的完成。Google 的一些工程师对此也很困惑，他们觉得， required 类型坏处大于好处，应该尽量仅适用 optional 或者 repeated 的。但 也并不是所有的人都这么想。 2.4 同一.proto 文件定义多个 message

PB 支持同一.proto 文件定义多个 message。这在需要定义相关 message 的 时候非常有用， 例如： 除了搜索请求 message， 还需要定义搜索响应 message， 可以再同一.proto 文件中定义： message SearchRequest {
required string query = 1;
optional int32 page_number = 2;
optional int32 result_per_page = 3;
}
message SearchResponse {
...
} 2.5 添加评论 使用 C/C++风格的注释 // syntax，如下例子： message SearchRequest {
required string query = 1;
optional int32 page_number = 2;// Which page number do we want?
optional int32 result_per_page = 3;// Number of results to return per page.
} 2.6 编译.proto 文件后产生了什么？

用 PB 编译器运行.proto 文件后，会按照定义的格式，生成指定语言的一系列 代买，这些代码的功能包括：字段值的 getter，setter，序列化 message 并 写入到输出流，从输入流接写成 message 等。 对于 Java，编译器生成一个.java 文件，该 java 文件内包含几个内部类，分别 对应.proto 文件中定义的 message 类型，以及将来用于创建 message 类实 例的 Builder 类。
3. 标准值类型
.proto Type double float int32 使用可变长 编码. 对于 负数比较低 效，如果负 数较多，请 使用 sint32 int64 使用可变长 编码. 对于 负数比较低 效，如果负 数较多，请 使用 sint64 uint32 使用可变长 编码 使用可变长 编码 使用可变长 编 uint32 int int/long int64 long int/long Notes C++ Type double float int32 Java Type double float int Python Type[2] float float int
uint64
uint64
long
int/long
sint32
int32
int
int

码. Signed int value. 编码负数比 int32 更高 效 sint64 使用可变长 编 码. Signed int value. 编码负数比 int64 更高 效 fixed32
恒定四个字节。 如果数值几乎总 是大于 2 的 28 次方，该类型比 unit32 更高效。
int64
long
int/long
uint32
int
int
fixed64
恒定四个字 节。如果数 值几乎总是 大于 2 的 56 次方， 该 类型比 unit64 更 高效。 恒定四个字 节 恒定八个字 节
uint64
long
int/long
sfixed32
int32
int
int
sfixed64
int64
long
int/long
bool string A string must always
bool string
boolean String
boolean str/unicode

contain UTF-8 encoded or 7-bit ASCII text. bytes 包含任意数 量顺序的字 节 string ByteString str
4. Optional 字段及其默认值
上面提到， PB 允许设置可选字段(optional)。 顾名思义， 在一条 message 中， 该字段可设值也可不设。假如没有设置，那么在解析该字段的时候，会根据该字 段类型，给其赋一个类型默认值。除此之外，也可以在定义 message 格式的时 候，就为 optional 字段设置一个默认值，如下： optional int32 result_per_page = 3 [default = 10]; 假如没有赋值的话，会被赋上默认值。对于简单类型，默认值可以自己设定，例 如上例的 PhoneNumber 中的 PhoneType 字段。如果没有自行设定，会被赋 上一个系统默认值， 数字类型会被赋为 0， String 类型会被赋为空字符串， bool 类型会被赋为 false。对于枚举类型，默认值是枚举列表中第一个值。
5. 枚举类型
在定义 message 类型的时候，也许会有这样一种需求：其中的一个字段仅需要 包含预定义的若干个值即可。比如，对于每一个搜索请求，现需要增加一个分类 字段， 分类包含： UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS or VIDEO。要实现该功能，仅需要增加一个枚举类型字段。如下： message SearchRequest { required string query = 1; optional int32 page_number = 2; optional int32 result_per_page = 3 [default = 10]; enum Corpus { UNIVERSAL = 0; WEB = 1; IMAGES = 2;

LOCAL = 3; NEWS = 4; PRODUCTS = 5; VIDEO = 6; } optional Corpus corpus = 4 [default = UNIVERSAL]; } 还可以给枚举值设置别名， 仅需将相同的数字标签设置给不同的名称即可。 这里， 必须得设置 allow_alias 为 true，否则 PB 编译器会报错。 enum EnumAllowingAlias { option allow_alias = true; UNKNOWN = 0; STARTED = 1; RUNNING = 1; }
enum EnumNotAllowingAlias { UNKNOWN = 0; STARTED = 1; // RUNNING = 1; // Uncommenting this line will cause a compile error inside Google and a warning message outside. } 可以定义枚举在一个 message 内部， 如上例。 也可以定义在 message 的外部， 这样的枚举可以被其他任何.proto 文件内的 message 复用。
6. 使用其他 Message 类型作为 filed 类型
PB 允许使用 message 类型作为 filed 类型。例如，在搜索相应 message 中， 包含一个结果 message。 此时， 只需要定义一个结果 message， 然后再.proto 文件中，在搜索结果 message 中新增一个字段，该字段的类型设置为结果 message 即可。如下： message SearchResponse { repeated Result result = 1;

}
message Result { required string url = 1; optional string title = 2; repeated string snippets = 3; } 6.1 导入定义 在上例中， Result message 类型与 SearchResponse 定义在同一个文件中， 假如有这么一种情况，这里所要使用的 Resultmessage 已经在其他的.proto 文件中定义了呢？ 可以通过导入其他.proto 文件来使用其内的定义。 为达此目的， 需要在现.proto 文件前增加一条 import 语句： import "myproject/other_protos.proto";
7. 嵌套类型
PB 支持 message 内嵌套 message，如下例子中，Result message 定义在 了 SearchResponse 内： message SearchResponse { message Result { required string url = 1; optional string title = 2; repeated string snippets = 3; } repeated Result result = 1; } 如果想要在父 Message 外复用该 message 的话，可以用 Parent.Type 格式 来引用。 message SomeOtherMessage { optional SearchResponse.Result result = 1; }

PB 支持无限深层次的 message 嵌套： message Outer { message MiddleAA { message Inner { // Level 1 // Level 2 // Level 0
required int64 ival = 1; optional bool } } message MiddleBB { message Inner { // Level 1 // Level 2 booly = 2;
required int32 ival = 1; optional bool } } } booly = 2;
8. 更新 Message 类型
如果现有 message 类型不能在满足业务需求，例如，需要新增一个字段，但是 我们却希望依然能够使用原来的.proto 生成的代码。完全没有问题，仅需记住 如下规则： 1. 千万不要修改现有字段后边的数值标签 2. 只能新增 optional 或者 repeated 字段 3. 可以删除非必须字段， 但是他们的数字标签不能再被使用。 最好的方法是不删除， 而是修改名字，比如在前缀上加 OBSOLETE_，这样就可以避免后人尽量少的 出错。 4. 非 required 字段可以转化成 extension 字段， 反之亦然， 同时保留原类型和数 字标签 5. int32, uint32, int64, uint64, 和 bool 是兼容的。 即这些字段可以相互切换， 在代码处理的时候， 不会出错， 但是小心范围小的数据接收范围大的数据会发生 截断 6. sint32, sint64 是相互兼容的，但是不与其他整型类型兼容 7. string 和 bytes 是兼容的，因为 bytes 也是合法的 UTF-8 8. Embedded messages are compatible with bytes if the bytes contain an encoded version of the message(不知道怎么翻译了) 9. fixed32 与 sfixed32 兼容， fixed64 与 sfixed64 兼容

10. optional 与 repeated 兼容，也存在数据截断，假如讲一个 repeated 的序列化后的数据作为输入给客户端，客户端会截取最后一个原子类型的字节。 或者，如果是一个 message 类型的字段的话，合并所有的元素。 11. 可以修改字段默认值
9. Package
PB 建议在.proto 文件开头添加一个 package 说明符来避免不同 message 类 型的名字冲突： package foo.bar;
message Open { ... } 这样，就可以使用该 package 标示符来定义该 message 类型的字段： message Foo {
...
required foo.bar.Open open = 1;
...
} 不同语言，因为添加 package 标示符，生成的代码也会有所不同，Java 中， 该 package 将会被用作 java 文件的 package。如果不想这样的话，也可 在.proto 文件中显式指明 package，该字段是：java_package。