Protobuf筆記

《Protobuf筆記》

Google Protocol Buffer 是一個平臺無關、語言無關的結構化資料的序列化與反序列化工具。

使用方式：
1) define proto files AddressBook.proto
2) Invoke protoc to build AddressBookProtos.java:
$ protoc --java_out=src/main/java -I../src
../src/google/protobuf/AddressBook.proto
eg. protoc --proto_path=. --java_out=. mytest/AddressBook.proto
3) Compile the code in src/main/java using whatever means you prefer.
4) Install the classes wherever you prefer.

proto檔案demo：
==================================================
package tutorial;

option java_package = "com.example.tutorial";
option java_outer_classname = "AddressBookProtos";

message Person {
required string name = 1;
required int32 id = 2; // Unique ID number for this person.
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;
}

// Our address book file is just one of these.
message AddressBook {
repeated Person person = 1;
}
==================================================

語法解釋：
在.proto檔案中，最基本的資料型別為message，其定義如上所示，由message引導，之後是message型別的名字，之後是由{}包含的各個域(fields)。

required string name = 1; 域字義的一個例子。
required 表示這個域是必需的
optional 該域選，出現０次或１次
repeated 重複出現，０次或多次

string是域的型別，可是簡單的標量型別（如bool,int32,float,double,string等），也可是複合型別(message,enum等)

name是域的名字，=1是給域一個數字標籤，這會影響到該域在二進位制檔案中順序。
關於這個數字標籤也是有說明的，1到15是隻使用一個位元組編號，而其他的使用多個位元組，所以應把1-15編號給最經常使用的域。數字標籤的最大值為2**29 - 1（或536,870,911），其中還有一段是保留用於proto的實現，從19000到19999 （FieldDescriptor::kFirstReservedNumber 到FieldDescriptor::kLastReservedNumber）。

有optional說明的域可以有一個預設值，在不指定該域時使用，如optional PhoneType type = 2 [default = HOME];

還有一種型別是enum，如上enum PhoneType的定義。型別可以定義一在一個message型別中，也可以單獨定義，如上enum PhoneType和message PhoneNumber是巢狀定義在message Person中，message AddressBook中單獨定義的。　　

可以訪問一個巢狀定義在另一個message型別中的message，但需使用域範圍標示，如同的c++裡使用另一個名稱空間的類：person::PhoneNumber。

新增註釋：//

　　optional int32 page_number = 2;// Which page number do we want?

匯入：proto可以匯入在不同的檔案中的定義。透過在檔案頂端加入一個import語句

　　import "myproject/other_protos.proto";

擴充套件：proto支援將一定範圍內的數字編號作為擴充套件時使用。對擴充套件的使用也需使用範圍方法。

　　message Foo {
　　 // ...
　　extensions 100 to 199;
　　}

　　extend Foo {
　　 optional int32 bar = 126;
　　}

包：proto支援包的使用，以防止命名衝突。在檔案的開始部分指定：package tutorial。不同的語言在生成程式碼對包的處理是不同的：c++中作為名稱空間，java中也作包，python中是模組。

Options：可使用option來指定一些選項，會對生成的程式碼有一些影響。option分檔案層的和域層的。在上面的例子中就使用了檔案層的：

　　option java_package = "com.example.tutorial";
　　option java_outer_classname = "AddressBookProtos";

生成程式碼：使用proto編譯器就可以生成相應語言的程式碼。

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR 　path/file.proto
　protoc.exe是編譯器的名字；--proto_path指定對匯入檔案的搜尋路徑，若不指定，則為當前路徑；--cpp_out指定生成c++檔案的路徑，--java_out和 --python_out分別是生成java和python程式碼的路徑；path/file.proto是定義結構的.proto檔案。

使用c++語言，會生成針對每個message型別的一個類，對每一個類也提供了相應的處理方法，還提供了序列化到輸出流和從輸入流中解析的方法。

相關資源：protobuf 元件包
protobuf-java-2.4.1.jar

google ProtoBuf開發者指南

http://www.cnblogs.com/foxhengxing/archive/2010/08/10/1796165.html

google protobuf doc

https://developers.google.com/protocol-buffers/docs/javatutorial?hl=zh-CN

[@more@]