Protocol Buffers(Protobuf) 官方文档--Protobuf语言指南

Protocol Buffers(Protobuf) 官方文档--Protobuf语言指南

约定：为方便书写，ProtocolBuffers在下文中将已Protobuf代替。

本指南将向您描述如何使用protobuf定义i结构化Protobuf数据，包括.proto文件语法和如何使用.proto文件生成数据存取类。

作为一个参考指南，本文档将以示例的形式一步步向您介绍Protobuf的特点。您可以参考您所选择的语言的示例。tutorial 

--------------------------------------小小的分割线-----------------------------------------

定义一个消息类型

首先，看一个非常简单的例子，比如说你想定义一个 搜索请求消息 ，每个搜索请求都有一个 查询的字符串(关键字:比如我们上百度搜索 《报告老板》),和我们搜索出来的一个感兴趣的网页，以及搜索到的所有网页总数。 来看看这个.proto文件是如何定义的。

 

1 message SearchRequest {
2   required string query = 1;
3   optional int32 page_number = 2;
4   optional int32 result_per_page = 3;
5 }

这个"搜索请求"消息指定了三个字段(名称/属性 组合)，每一个你想要包含在这类型的信息内的东西，都必须有一个字段，每个字段有一个名称和类型！

指定字段类型

在上面的示例中，所有的字段都是标量类型(scalar types):两个整数(integers：page_number 和 result_per_page)和一个字符串(string:query:查询的关键字),不过你可以在你的字段内指定符合类型。包括枚举类型(enumerations)和其他的消息类型

分配指定标签号

如你所见，每个消息的字段都有一个唯一的数字标签,这些标签用来表示你的字段在二进制消息(message binary format)中处的位置。并且一旦指定标签号，在使用过程中是不可以更改的,标记这些标签号在1-15的范围内每个字段需要使用1个字节用来编码这一个字节包括字段所在的位置和字段的类型！(需要更多关于编码的信息请点击Protocol Buffer Encoding)。标签号在16-2047需要使用2个字节来编码。所以你最好将1-15的标签号为频繁使用到的字段所保留。如果将来可能会添加一些频繁使用到的元素，记得留下一些1-15标签号。

最小可指定的标签号为1，最大的标签号为229 - 1或者536870911。不能使用19000-19999的标签号(FieldDescriptor::kFirstReservedNumber 至 FieldDescriptor::kLastReservedNumber) 这些标签号是为protobuf内部实现所保留的，如果你在.proto文件内使用了这些标签号Protobuf编译器将会报错！

 

指定字段规则

消息字段可以被指定为以下三种:

  • required: 完整的消息内必须拥有此字段。此字段是必须拥有的 (双方都要有)
  • optional: 完整的消息内此字段是可选的，可拥有也可以没有(双方可选)
  • repeated: 完整的消息内本字段的值可以拥有任意个，重复的值的次数会保存下来。(双方可选,数组)

因为历史的原因：repeated字段如果是基本的数字类型的话会无法编码。新的代码应该使用特殊的关键字[packed=true] 来使其得到有效的编码.例如

[cpp] view plaincopyprint?
 
  1. repeated int32 samples = 4 [packed=true];  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. repeated int32 samples = 4 [packed=true];  

注意：你应该小心将字段设置为required，如果你希望在某些情况下取消required字段的读写，它将改变字段为optional属性,旧的的读取方将会认为此消息不完全。可能会无意的将其丢弃。你应该考虑自定义一个消息检查程序。google的一些工程师认为使用optinal字段的好处大于required。但是显然这个观点并不是通用的。

添加更多的消息类型

多个消息类型可以定义在同一个.proto文件内,这对定义多个有关联的消息是是十分有用的。例如，如果你想定义一个用于回复SearchResponse消息，你可以像这样在.proto内添加。

[cpp] view plaincopyprint?
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;  
  4.   optional int32 result_per_page = 3;  
  5. }  
  6.   
  7. message SearchResponse {  
  8.  ...  
  9. }  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;  
  4.   optional int32 result_per_page = 3;  
  5. }  
  6.   
  7. message SearchResponse {  
  8.  ...  
  9. }  

 

添加注释

添加注释的方式和C/C++是一样的。使用//

[cpp] view plaincopyprint?
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;// Which page number do we want?  
  4.   optional int32 result_per_page = 3;// Number of results to return per page.  
  5. }  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;// Which page number do we want?  
  4.   optional int32 result_per_page = 3;// Number of results to return per page.  
  5. }  

 

.proto文件会生成什么？

当你使用protobuf编译器编译一个.proto文件，它会生成在.proto内你描述的消息类型的操作代码，这些代码是根据你所选择的编程功能语言决定的。这些操作代码内包含了设置字段值 和读取字段值，以及序列化到输出流 和 从输入流反序列化。

C++:编译器会按照每个.proto文件生成与其对应的.h和.cc文件,每个消息类似都有独立的消息操作类。

Java:编译器将会生成一个.java文件和一个操作类，此操作类为所有消息类型所共有, 使用一个特别的Builder类为每个消息类型实例化.

Python:有一点不同 – 编译器会为每个消息生成一个模块每个模块有一个静态描述符, 该模块与一个元类在运行时创建一个需要的数据操作类。

从你所选择语言的例程，你可以找到更多关于API的内容， 需要关于API的详细信息, 参考： API reference.

标量值类型

一个消息的字段如果要使用标量可使之为以下类型 –这个表格显示了在.proto文件内可以指定的类型, 与自动生成的相对类型！

.proto TypeNotesC++ TypeJava TypePython Type[2]
double   double double float
float   float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long[3]
uint32 Uses variable-length encoding. uint32 int[1] int/long[3]
uint64 Uses variable-length encoding. uint64 long[1] int/long[3]
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long[3]
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 228. uint32 int[1] int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 256. uint64 long[1] int/long[3]
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long[3]
bool   bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode[4]
bytes May contain any arbitrary sequence of bytes. string ByteString str

 

你可以在Protocol Buffer Encoding.找到更多关于.这些类型如何编码，如何序列化定义消息的信息！

[1] 在Java中, 无符号32位和64位整数与其有符号相对应, 最高位用来保存符号！

[2] 在所有情况下, 设置某个字段的值将会执行类型检查确保其值是合法的！

[3] 64位或32位无符号整数在解码中会以long来解码, 给字段赋值的时候可以是int.但是在所有情况下,赋值的时候会转变为其目标类型 . 详见 [2].

[4] Python的字符串在解码时候会以unicode来描述，但是同样的可以给其赋值为ascii字符串  (此乃弦外之音).

 

Optional 字段与其默认值

如上所述，在描述一个消息的时候可以用optional指定字段约束，一个消息可以包含也可以不包含optional元素。当一个消息被解析，如果其没有一个optional字段，被解析的消息对象就会将其相对的字段设置为其字段的默认值。这个默认值可以在描述消息的时候被指定。例如。比如你想设置SearchRequest的 result_per_page的默认值为10.

[cpp] view plaincopyprint?
 
  1. optional int32 result_per_page = 3 [default = 10];  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. optional int32 result_per_page = 3 [default = 10];  

 如果一个optional字段没有被指定其默认值。其默认值被自动替换为：

1.字符串:为空字符串.

2.bool:为false.

3.数字类型:为0；

4.枚举值:为第一个枚举值

枚举值

当你定义消息格式的时候, 也许你希望其中的一个字段的的值为一个预定义的值类表中的一个. 比方说, 在SearchRequest消息中你想定义一个 corpus 字段， corpus字段的值可以为:" UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS 或者 VIDEO". 你可以非常简单的给你的消息添加一个枚举类型 - 一个枚举字段类型其值指定被指定为一个常量的集合 (如果你尝试赋值一个不一样的值, 解析器将会认为这个字段为未知字段). 在下面的例子中 我们给corpus字段指定为枚举类型与其可能的值 :

[cpp] view plaincopyprint?
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;  
  4.   optional int32 result_per_page = 3 [default = 10];  
  5.   enum Corpus {  
  6.     UNIVERSAL = 0;  
  7.     WEB = 1;  
  8.     IMAGES = 2;  
  9.     LOCAL = 3;  
  10.     NEWS = 4;  
  11.     PRODUCTS = 5;  
  12.     VIDEO = 6;  
  13.   }  
  14.   optional Corpus corpus = 4 [default = UNIVERSAL];  
  15. }  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. message SearchRequest {  
  2.   required string query = 1;  
  3.   optional int32 page_number = 2;  
  4.   optional int32 result_per_page = 3 [default = 10];  
  5.   enum Corpus {  
  6.     UNIVERSAL = 0;  
  7.     WEB = 1;  
  8.     IMAGES = 2;  
  9.     LOCAL = 3;  
  10.     NEWS = 4;  
  11.     PRODUCTS = 5;  
  12.     VIDEO = 6;  
  13.   }  
  14.   optional Corpus corpus = 4 [default = UNIVERSAL];  
  15. }  

你可以为一个枚举常量定义别名，如果你需要这样做的话需要将allow_alias设置为true。否则如果出现别名的话编译器将会报错！　

[cpp] view plaincopyprint?
 
  1. enum EnumAllowingAlias {  
  2.   option allow_alias = true;  
  3.   UNKNOWN = 0;  
  4.   STARTED = 1;  
  5.   RUNNING = 1;  
  6. }  
  7. enum EnumNotAllowingAlias {  
  8.   UNKNOWN = 0;  
  9.   STARTED = 1;  
  10.   // RUNNING = 1;  //不注释这行的话会引发一个错误异常  
[cpp] view plaincopyprint?在CODE上查看代码片派生到我的代码片
 
  1. enum EnumAllowingAlias {  
  2.   option allow_alias = true;  
  3.   UNKNOWN = 0;  
  4.   STARTED = 1;  
  5.   RUNNING = 1;  
  6. }  
  7. enum EnumNotAllowingAlias {  
  8.   UNKNOWN = 0;  
  9.   STARTED = 1;  
  10.   // RUNNING = 1;  //不注释这行的话会引发一个错误异常  

枚举值的范围必须在32位整数之内.枚举值的编码使用可变长度的整数，负数会非常低效所以，不推荐使用。你可以在一个消息内部定义一个枚举类型，比如上面的例子。或者也可以在消息的外部定义。这些枚举类型是可以在.proto文件内中重用的，你可以在消息内定义个枚举类型。然后在不同的消息类型中使用它！可以使用 MessageType.EnumType来访问。当你运行编译器编译.proto文件中的枚举类型时，生成的代码会有一个相对应的枚举值(JAVA 或者C++),或者有一个特别的EnumDescriptor类(python)用于在运行时生成一个符号常量集合。

更多关于枚举类型的信息查询 generated code guide 选择你使用的语言。

 待续....................

posted @ 2015-05-06 21:58  菜鸡一枚  阅读(1769)  评论(0)  编辑  收藏  举报