一. 簡單介紹

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

?

二. Protobuf消息定義

---

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

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

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

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

?

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

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

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

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

?

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

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

????

protobuf 數(shù)據(jù)類型	描述	打包	C++語言映射
bool	布爾類型	1字節(jié)	bool
double	64位浮點數(shù)	N	double
float	32為浮點數(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ù)，處理負數(shù)效率更高	N	int32
sing64	64位整數(shù) 處理負數(shù)效率更高	N	__int64
fixed32	32位無符號整數(shù)	4	unsigned int32
fixed64	64位無符號整數(shù)	8	unsigned __int64
sfixed32	32位整數(shù)、能以更高的效率處理負數(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ù)項目的實際情況，一般選擇fixed32，如果遇到對傳輸數(shù)據(jù)量要求比較苛刻的環(huán)境，可以選擇int32.

3）字段名稱

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

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

4）字段編碼值

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

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

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

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

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

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

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

?

5）默認值。

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

?

?

三. Protobuf其它可選項

---

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

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

文件級別，這樣的選項將影響當前文件中定義的所有消息和枚舉。

消息級別，這樣的選項僅影響某個消息及其包含的所有字段。

字段級別，這樣的選項僅僅響應與其相關(guān)的字段。

java_package可選項

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

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

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

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

?

java_outer_classname可選項

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

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

則該選項不起任何作用。

如：option java_outer_classname = "Ponycopter";

?

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

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

引入到當前Java文件中，

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

?

四. 注意事項

---

1）關(guān)于import

protobuf 接口文件可以像C語言的h文件一個，分離為多個，在需要的時候通過 import導入需要對文件。其行為和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示例注意事項

示例：

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;

}

?

注意事項：

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消息時，變量前面不能添加修飾符，否則報錯；

?

?

?

?

總結(jié)

以上是生活随笔為你收集整理的Protobuf之proto文件编写规则的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。