Protocol Buffers定义协议格式

原文地址：http://www.cnblogs.com/shitouer/archive/2013/04/10/google-protocol-buffers-tutorial.html

首先需要创建一个.proto文件。非常简单，每一个需要序列化的数据结构，编码一个PB message，然后为message中的字段指明一个名字和类型即可。该“通讯簿”的.proto 文件addressbook.proto定义如下：

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

package tutorial; option java_package = "com.example.tutorial"; option java_outer_classname = "AddressBookProtos";   message Person {    required string name = 1;    required int32 id = 2;    optional string email = 3;      enum PhoneType {      MOBILE = 0;      HOME = 1;      WORK = 2;    }      message PhoneNumber {      required string number = 1;      optional PhoneType type = 2 [default = HOME];    }      repeated PhoneNumber phone = 4; } message AddressBook {    repeated Person person = 1; }

可以看到，语法非常类似Java或者C++，接下来，我们一条一条来过一遍每句话的含义：

• .proto文件以一个package声明开始。该声明有助于避免不同项目建设的命名冲突。Java版的PB，在没有指明java_package的情况下，生成的类默认的package即为此package。这里我们生命的java_package，所以最终生成的类会位于com.example.tutorial package下。这里需要强调一下，即使指明了java_package，我们建议依旧定义.proto文件的package。
• 在package声明之后，紧接着是专门为java指定的两个选项：java_package 以及 java_outer_classname。java_package我们已经说过，不再赘述。java_outer_classname为生成类的名字，该类包含了所有在.proto中定义的类。如果该选项不显式指明的话，会按照驼峰规则，将.proto文件的名字作为该类名。例如“addressbook.proto”将会是“Addressbook”，“address_book.proto”即为“AddressBook”
• java指定选项后边，即为message定义。每个message是一个包含了一系列指明了类型的字段的集合。这里的字段类型包含大多数的标准简单数据类型，包括bool，int32，float，double以及string。Message中也可以定义嵌套的message，例如“Person” message 包含“PhoneNumber” message。也可以将已定义的message作为新的数据类型，例如上例中，PhoneNumber类型在Person内部定义，但他是phone的type。在需要一个字段包含预先定义的一个列表的时候，也可以定义枚举类型，例如“PhoneType”。
• 我们注意到， 每一个message中的字段，都有“=1”，“=2”这样的标记，这可不是初始化赋值，该值是message中，该字段的唯一标示符，在二进制编码时候会用到。数字1~15的表示需求少于一个字节，所以在编码的时候，有这样一个优化，你可以用1~15标记最常使用或者重复字段元素(repeated elements)。用16或者更大的数字来标记不太常用的可选元素。再重复字段中，每一个元素都需重复编码标签数字，所以，该优化对重复字段最佳(repeat fileds)。

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的数组就可以了。

 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的。但也并不是所有的人都这么想。

如果想深入学习.proto文件书写，可以参考Protocol Buffer Language Guide。但是不要妄想会有类似于类继承这样的机制，Protocol Buffers不做这个...

更新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. 可以修改字段默认值