Protobuf之proto文件編寫規(guī)則

protobuf文件：就是定義你要的消息（類似java中的類）和消息中的各個字段及其數(shù)據(jù)類型（類似java類中的成員變量和他的數(shù)據(jù)類型）

?

1、消息由至少一個字段組合而成，類似于C語言中的結(jié)構(gòu)。每個字段都有一定的格式。

字段格式：限定修飾符① | 數(shù)據(jù)類型② | 字段名稱③ | = | 字段編碼值④ | [字段默認(rèn)值⑤]

2、文件開頭syntax="proto2";?表明使用protobuf的編譯器版本為v2，目前最新的版本為v3。

3、?package addressbook;?聲明了一個包名，用來防止不同的消息類型命名沖突，類似于?namespace?。

?

1）限定修飾符包含 required\optional\repeated

Required: 表示是一個必須字段，必須相對于發(fā)送方，在發(fā)送消息之前必須設(shè)置該字段的值，對于接收方，必須能夠識別該字段的意思。發(fā)送之前沒有設(shè)置required字段或者無法識別required字段都會引發(fā)編解碼異常，導(dǎo)致消息被丟棄。

Optional：表示是一個可選字段，可選對于發(fā)送方，在發(fā)送消息時，可以有選擇性的設(shè)置或者不設(shè)置該字段的值。對于接收方，如果能夠識別可選字段就進(jìn)行相應(yīng)的處理，如果無法識別，則忽略該字段，消息中的其它字段正常處理。---因?yàn)閛ptional字段的特性，很多接口在升級版本中都把后來添加的字段都統(tǒng)一的設(shè)置為optional字段，這樣老的版本無需升級程序也可以正常的與新的軟件進(jìn)行通信，只不過新的字段無法識別而已，因?yàn)椴⒉皇敲總€節(jié)點(diǎn)都需要新的功能，因此可以做到按需升級和平滑過渡。

Repeated：表示該字段可以包含[0,N]個元素。其特性和optional一樣，但是每一次可以包含多個值。可以看作是在傳遞一個數(shù)組的值。?

?

2）數(shù)據(jù)類型?

Protobuf定義了一套基本數(shù)據(jù)類型。幾乎都可以映射到C++\Java等語言的基礎(chǔ)數(shù)據(jù)類型.? ??

????

protobuf 數(shù)據(jù)類型

描述

打包

C++語言映射

bool

布爾類型

1字節(jié)

bool

double

64位浮點(diǎn)數(shù)

N

double

float

32為浮點(diǎn)數(shù)

N

float

int32

32位整數(shù)、

N

int

uin32

無符號32位整數(shù)

N

unsigned int

int64

64位整數(shù)

N

__int64

uint64

64為無符號整

N

unsigned __int64

sint32

32位整數(shù)，處理負(fù)數(shù)效率更高

N

int32

sing64

64位整數(shù) 處理負(fù)數(shù)效率更高

N

__int64

fixed32

32位無符號整數(shù)

4

unsigned int32

fixed64

64位無符號整數(shù)

8

unsigned __int64

sfixed32

32位整數(shù)、能以更高的效率處理負(fù)數(shù)

4

unsigned int32

sfixed64

64為整數(shù)

8

unsigned __int64

string

只能處理 ASCII字符

N

std::string

bytes

用于處理多字節(jié)的語言字符、如中文

N

std::string

enum

可以包含一個用戶自定義的枚舉類型uint32

N(uint32)

enum

message

可以包含一個用戶自定義的消息類型

N

object of class

?

N 表示打包的字節(jié)并不是固定。而是根據(jù)數(shù)據(jù)的大小或者長度。

例如int32，如果數(shù)值比較小，在0~127時，使用一個字節(jié)打包。

關(guān)于枚舉的打包方式和uint32相同。

關(guān)于message，類似于C語言中的結(jié)構(gòu)包含另外一個結(jié)構(gòu)作為數(shù)據(jù)成員一樣。

關(guān)于 fixed32 和int32的區(qū)別。fixed32的打包效率比int32的效率高，但是使用的空間一般比int32多。因此一個屬于時間效率高，一個屬于空間效率高。根據(jù)項(xiàng)目的實(shí)際情況，一般選擇fixed32，如果遇到對傳輸數(shù)據(jù)量要求比較苛刻的環(huán)境，可以選擇int32.

3）字段名稱

字段名稱的命名與C、C++、Java等語言的變量命名方式幾乎是相同的。

protobuf建議字段的命名采用以下劃線分割的駝峰式。例如 first_name 而不是firstName.

4）字段編碼值

有了該值，通信雙方才能互相識別對方的字段。當(dāng)然相同的編碼值，其限定修飾符和數(shù)據(jù)類型必須相同。

編碼值的取值范圍為 1~2^32（4294967296）。

其中 1~15的編碼時間和空間效率都是最高的，編碼值越大，其編碼的時間和空間效率就越低（相對于1-15），當(dāng)然一般情況下相鄰的2個值編碼效率的是相同的，除非2個值恰好實(shí)在4字節(jié)，12字節(jié)，20字節(jié)等的臨界區(qū)。比如15和16.

1900~2000編碼值為Google protobuf 系統(tǒng)內(nèi)部保留值，建議不要在自己的項(xiàng)目中使用。

protobuf 還建議把經(jīng)常要傳遞的值把其字段編碼設(shè)置為1-15之間的值。

消息中的字段的編碼值無需連續(xù)，只要是合法的，并且不能在同一個消息中有字段包含相同的編碼值。

建議：項(xiàng)目投入運(yùn)營以后涉及到版本升級時的新增消息字段全部使用optional或者repeated，盡量不實(shí)用required。如果使用了required，需要全網(wǎng)統(tǒng)一升級，如果使用optional或者repeated可以平滑升級。

?

5）默認(rèn)值。

當(dāng)在傳遞數(shù)據(jù)時，對于required數(shù)據(jù)類型，如果用戶沒有設(shè)置值，則使用默認(rèn)值傳遞到對端。當(dāng)接受數(shù)據(jù)是，對于optional字段，如果沒有接收到optional字段，則設(shè)置為默認(rèn)值。

?

?

Protocol Buffer允許我們在.proto文件中定義一些常用的選項(xiàng)，這樣可以指示Protocol Buffer編譯器幫助我們生成更為匹配的目標(biāo)語言代碼。

Protocol Buffer內(nèi)置的選項(xiàng)被分為以下三個級別：

java_package可選項(xiàng)

java_package (file option): 是文件級別的選項(xiàng)，表明生成java類所在的包。如果在.proto文件中沒有明確的聲明java_package，就采用默認(rèn)的包名。

當(dāng)然了，默認(rèn)方式產(chǎn)生的 java包名并不是最好的方式，按照應(yīng)用名稱倒序方式進(jìn)行排序的。如果不需要產(chǎn)生java代碼，則該選項(xiàng)將不起任何作用。

與此同時，生成的Java文件也將會自動存放到指定輸出目錄下的com/example/foo子目錄中。

如：option java_package = "com.example.foo";

?

java_outer_classname可選項(xiàng)

java_outer_classname (file option): 是文件級別的選項(xiàng)，表明想要生成Java類的名稱。如果在.proto文件中沒有明確的java_outer_classname定義，

生成的class名稱將會根據(jù).proto文件的名稱采用駝峰式的命名方式進(jìn)行生成。如（foo_bar.proto生成的java類名為FooBar.java）,如果不生成java代碼，

則該選項(xiàng)不起任何作用。

如：option java_outer_classname = "Ponycopter";

?

注：主要是因?yàn)镴ava中要求同一個.java文件中只能包含一個Java外部類或外部接口，而C++則不存在此限制。因此在.proto文件中定義的消息均為

指定外部類的內(nèi)部類，這樣才能將這些消息生成到同一個Java文件中。在實(shí)際的使用中，為了避免總是輸入該外部類限定符，可以將該外部類靜態(tài)

引入到當(dāng)前Java文件中，

如：import static com.company.project.LYPhoneMessage.*。

?

1）關(guān)于import

protobuf 接口文件可以像C語言的h文件一個，分離為多個，在需要的時候通過 import導(dǎo)入需要對文件。其行為和C語言的#include或者java的import的行為大致相同。

2）關(guān)于package

避免名稱沖突，可以給每個文件指定一個package名稱，對于java解析為java中的包。對于C++則解析為名稱空間。

3）關(guān)于message

支持嵌套消息，消息可以包含另一個消息作為其字段。也可以在消息內(nèi)定義一個新的消息。

關(guān)于enum

枚舉的定義和C++相同，但是有一些限制。

枚舉值必須大于等于0的整數(shù)。

使用分號(;)分隔枚舉變量而不是C++語言中的逗號(,)

4）message示例注意事項(xiàng)

示例：

syntax="proto2";

package FunMember; //命名空間

//分頁請求參數(shù)

message PagerRequest{

? ?optional int32 PageIndex=1;

? ?required PageSize=2;

? ?repeated User Modle=3;

}

message User{

? ?int32 userId=1;

? ?int32 memberId=2;

}

?

注意事項(xiàng)：

1、如果ProtoGenTools工具下載的是2.0的，則proto文件中開頭一句

syntax="proto2";這里也必須是proto2，如果定義為proto3就會報錯；

?

2、生成C#的.cs文件，使用的是protogen.exe工具，

生成Java，C#，Python文件，使用的是protoc.exe工具；

?

3、生成C#的.cs文件，定義proto文件的message消息時，變量前面必須添加修飾符：required\optional\repeated，否則報錯；

生成Java，C#，Python文件，，定義proto文件的message消息時，變量前面不能添加修飾符，否則報錯；

?

?

?

?