Protobuf语言指南
l 定义一个消息（message）类型
l 标量值类型
l Optional 的字段及默认值
l 枚举
l 使用其他消息类型
l 嵌套类型
l 更新一个消息类型
l 扩展
l 包（package）
l 定义服务（service）
l 选项（option）
l 生成访问类
本指南描述了怎样使用protocolbuffer语言来构造你的protocol buffer数据，包括.proto文件语法以及怎样生成.proto文件的数据访问类。
本文是一个参考指南——如果要查看如何使用本文中描述的多个特性的循序渐进的例子，请在http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/tutorials.html中查找需要的语言的教程。
l 定义一个消息类型
先来看一个非常简单的例子。假设你想定义一个“搜索请求”的消息格式，每一个请求含有一个查询字符串、你感兴趣的查询结果所在的页数，以及每一页多少条查询结果。可以采用如下的方式来定义消息类型的.proto文件了：
| message SearchRequest { required string query = 1; optional int32 page_number = 2; optional int32 result_per_page = 3; } |
SearchRequest消息格式有3个字段，在消息中承载的数据分别对应于每一个字段。其中每个字段都有一个名字和一种类型。
Ø 指定字段类型
在上面的例子中，所有字段都是标量类型：两个整型（page_number和result_per_page），一个string类型（query）。当然，你也可以为字段指定其他的合成类型，包括枚举（enumerations）或其他消息类型。
Ø 分配标识号
正如上述文件格式，在消息定义中，每个字段都有唯一的一个标识符。这些标识符是用来在消息的二进制格式中识别各个字段的，一旦开始使用就不能够再改 变。注：[1,15]之内的标识号在编码的时候会占用一个字节。[16,2047]之内的标识号则占用2个字节。所以应该为那些频繁出现的消息元素保留 [1,15]之内的标识号。切记：要为将来有可能添加的、频繁出现的标识号预留一些标识号。
最小的标识号可以从1开始，最大到229 - 1, or 536,870,911。不可以使用其中的[19000－19999]的标识号， Protobuf协议实现中对这些进行了预留。如果非要在.proto文件中使用这些预留标识号，编译时就会报警。
Ø 指定字段规则
所指定的消息字段修饰符必须是如下之一：
² required：一个格式良好的消息一定要含有1个这种字段。表示该值是必须要设置的；
² optional：消息格式中该字段可以有0个或1个值（不超过1个）。
² repeated：在一个格式良好的消息中，这种字段可以重复任意多次（包括0次）。重复的值的顺序会被保留。表示该值可以重复，相当于java中的List。
由于一些历史原因，基本数值类型的repeated的字段并没有被尽可能地高效编码。在新的代码中，用户应该使用特殊选项[packed=true]来保证更高效的编码。如：
| repeated int32 samples = 4 [packed=true]; |
required是永久性的：在将一个字段标识为required的时候，应该特别小心。如果在某些情况下不想写入或者发送一个required的 字段，将原始该字段修饰符更改为optional可能会遇到问题——旧版本的使用者会认为不含该字段的消息是不完整的，从而可能会无目的的拒绝解析。在这 种情况下，你应该考虑编写特别针对于应用程序的、自定义的消息校验函数。Google的一些工程师得出了一个结论：使用required弊多于利；他们更 愿意使用optional和repeated而不是required。当然，这个观点并不具有普遍性。
Ø 添加更多消息类型
在一个.proto文件中可以定义多个消息类型。在定义多个相关的消息的时候，这一点特别有用——例如，如果想定义与SearchResponse消息类型对应的回复消息格式的话，你可以将它添加到相同的.proto文件中，如：
| message SearchRequest { required string query = 1; optional int32 page_number = 2; optional int32 result_per_page = 3; }
message SearchResponse { … } |
Ø 添加注释
向.proto文件添加注释，可以使用C/C++/java风格的双斜杠（//） 语法格式，如：
| message SearchRequest { required string query = 1; optional int32 page_number = 2;// 最终返回的页数 optional int32 result_per_page = 3;// 每页返回的结果数 } |
Ø 从.proto文件生成了什么？
当用protocolbuffer编译器来运行.proto文件时，编译器将生成所选择语言的代码，这些代码可以操作在.proto文件中定义的消息类型，包括获取、设置字段值，将消息序列化到一个输出流中，以及从一个输入流中解析消息。
² 对C++来说，编译器会为每个.proto文件生成一个.h文件和一个.cc文件，.proto文件中的每一个消息有一个对应的类。
² 对Java来说，编译器为每一个消息类型生成了一个.java文件，以及一个特殊的Builder类（该类是用来创建消息类接口的）。
² 对Python来说，有点不太一样——Python编译器为.proto文件中的每个消息类型生成一个含有静态描述符的模块，，该模块与一个元类（metaclass）在运行时（runtime）被用来创建所需的Python数据访问类。
你可以从如下的文档链接中获取每种语言更多API。http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/reference/overview.html
l 标量数值类型
一个标量消息字段可以含有一个如下的类型——该表格展示了定义于.proto文件中的类型，以及与之对应的、在自动生成的访问类中定义的类型：
| .proto类型 |
Java 类型 |
C++类型 |
备注 |
| double |
double |
double |
|
| float |
float |
float |
|
| int32 |
int |
int32 |
使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint32。 |
| int64 |
long |
int64 |
使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint64。 |
| uint32 |
int[1] |
uint32 |
Uses variable-length encoding. |
| uint64 |
long[1] | uint64 | Uses variable-length encoding. |
| sint32 |
int |
int32 |
使用可变长编码方式。有符号的整型值。编码时比通常的int32高效。 |
| sint64 |
long |
int64 |
使用可变长编码方式。有符号的整型值。编码时比通常的int64高效。 |
| fixed32 |
int[1] |
uint32 |
总是4个字节。如果数值总是比总是比228大的话，这个类型会比uint32高效。 |
| fixed64 |
long[1] |
uint64 |
总是8个字节。如果数值总是比总是比256大的话，这个类型会比uint64高效。 |
| sfixed32 |
int |
int32 |
总是4个字节。 |
| sfixed64 |
long |
int64 |
