Protobuf之proto文件编写规则
一. 簡單介紹
protobuf文件：就是定義你要的消息（類似java中的類）和消息中的各個(gè)字段及其數(shù)據(jù)類型（類似java類中的成員變量和他的數(shù)據(jù)類型）
?
二. Protobuf消息定義
1、消息由至少一個(gè)字段組合而成，類似于C語言中的結(jié)構(gòu)。每個(gè)字段都有一定的格式。
字段格式：限定修飾符① | 數(shù)據(jù)類型② | 字段名稱③ | = | 字段編碼值④ | [字段默認(rèn)值⑤]
2、文件開頭syntax="proto2";?表明使用protobuf的編譯器版本為v2，目前最新的版本為v3。
3、?package addressbook;?聲明了一個(gè)包名，用來防止不同的消息類型命名沖突，類似于?namespace?。
?
1）限定修飾符包含 required\optional\repeated
Required: 表示是一個(gè)必須字段，必須相對于發(fā)送方，在發(fā)送消息之前必須設(shè)置該字段的值，對于接收方，必須能夠識(shí)別該字段的意思。發(fā)送之前沒有設(shè)置required字段或者無法識(shí)別required字段都會(huì)引發(fā)編解碼異常，導(dǎo)致消息被丟棄。
Optional：表示是一個(gè)可選字段，可選對于發(fā)送方，在發(fā)送消息時(shí)，可以有選擇性的設(shè)置或者不設(shè)置該字段的值。對于接收方，如果能夠識(shí)別可選字段就進(jìn)行相應(yīng)的處理，如果無法識(shí)別，則忽略該字段，消息中的其它字段正常處理。---因?yàn)閛ptional字段的特性，很多接口在升級(jí)版本中都把后來添加的字段都統(tǒng)一的設(shè)置為optional字段，這樣老的版本無需升級(jí)程序也可以正常的與新的軟件進(jìn)行通信，只不過新的字段無法識(shí)別而已，因?yàn)椴⒉皇敲總€(gè)節(jié)點(diǎn)都需要新的功能，因此可以做到按需升級(jí)和平滑過渡。
Repeated：表示該字段可以包含[0,N]個(gè)元素。其特性和optional一樣，但是每一次可以包含多個(gè)值。可以看作是在傳遞一個(gè)數(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 | 無符號(hào)32位整數(shù) | N | unsigned int |
| int64 | 64位整數(shù) | N | __int64 |
| uint64 | 64為無符號(hào)整 | N | unsigned __int64 |
| sint32 | 32位整數(shù)，處理負(fù)數(shù)效率更高 | N | int32 |
| sing64 | 64位整數(shù) 處理負(fù)數(shù)效率更高 | N | __int64 |
| fixed32 | 32位無符號(hào)整數(shù) | 4 | unsigned int32 |
| fixed64 | 64位無符號(hào)整數(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 | 可以包含一個(gè)用戶自定義的枚舉類型uint32 | N(uint32) | enum |
| message | 可以包含一個(gè)用戶自定義的消息類型 | N | object of class |
?
N 表示打包的字節(jié)并不是固定。而是根據(jù)數(shù)據(jù)的大小或者長度。
例如int32，如果數(shù)值比較小，在0~127時(shí)，使用一個(gè)字節(jié)打包。
關(guān)于枚舉的打包方式和uint32相同。
關(guān)于message，類似于C語言中的結(jié)構(gòu)包含另外一個(gè)結(jié)構(gòu)作為數(shù)據(jù)成員一樣。
關(guān)于 fixed32 和int32的區(qū)別。fixed32的打包效率比int32的效率高，但是使用的空間一般比int32多。因此一個(gè)屬于時(shí)間效率高，一個(gè)屬于空間效率高。根據(jù)項(xiàng)目的實(shí)際情況，一般選擇fixed32，如果遇到對傳輸數(shù)據(jù)量要求比較苛刻的環(huán)境，可以選擇int32.
3）字段名稱
字段名稱的命名與C、C++、Java等語言的變量命名方式幾乎是相同的。
protobuf建議字段的命名采用以下劃線分割的駝峰式。例如 first_name 而不是firstName.
4）字段編碼值
有了該值，通信雙方才能互相識(shí)別對方的字段。當(dāng)然相同的編碼值，其限定修飾符和數(shù)據(jù)類型必須相同。
編碼值的取值范圍為 1~2^32（4294967296）。
其中 1~15的編碼時(shí)間和空間效率都是最高的，編碼值越大，其編碼的時(shí)間和空間效率就越低（相對于1-15），當(dāng)然一般情況下相鄰的2個(gè)值編碼效率的是相同的，除非2個(gè)值恰好實(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ù)，只要是合法的，并且不能在同一個(gè)消息中有字段包含相同的編碼值。
建議：項(xiàng)目投入運(yùn)營以后涉及到版本升級(jí)時(shí)的新增消息字段全部使用optional或者repeated，盡量不實(shí)用required。如果使用了required，需要全網(wǎng)統(tǒng)一升級(jí)，如果使用optional或者repeated可以平滑升級(jí)。
?
5）默認(rèn)值。
當(dāng)在傳遞數(shù)據(jù)時(shí)，對于required數(shù)據(jù)類型，如果用戶沒有設(shè)置值，則使用默認(rèn)值傳遞到對端。當(dāng)接受數(shù)據(jù)是，對于optional字段，如果沒有接收到optional字段，則設(shè)置為默認(rèn)值。
?
?
三. Protobuf其它可選項(xiàng)
Protocol Buffer允許我們在.proto文件中定義一些常用的選項(xiàng)，這樣可以指示Protocol Buffer編譯器幫助我們生成更為匹配的目標(biāo)語言代碼。
Protocol Buffer內(nèi)置的選項(xiàng)被分為以下三個(gè)級(jí)別：
java_package可選項(xiàng)
java_package (file option): 是文件級(jí)別的選項(xiàng)，表明生成java類所在的包。如果在.proto文件中沒有明確的聲明java_package，就采用默認(rèn)的包名。
當(dāng)然了，默認(rèn)方式產(chǎn)生的 java包名并不是最好的方式，按照應(yīng)用名稱倒序方式進(jìn)行排序的。如果不需要產(chǎn)生java代碼，則該選項(xiàng)將不起任何作用。
與此同時(shí)，生成的Java文件也將會(huì)自動(dòng)存放到指定輸出目錄下的com/example/foo子目錄中。
如：option java_package = "com.example.foo";
?
java_outer_classname可選項(xiàng)
java_outer_classname (file option): 是文件級(jí)別的選項(xiàng)，表明想要生成Java類的名稱。如果在.proto文件中沒有明確的java_outer_classname定義，
生成的class名稱將會(huì)根據(jù).proto文件的名稱采用駝峰式的命名方式進(jìn)行生成。如（foo_bar.proto生成的java類名為FooBar.java）,如果不生成java代碼，
則該選項(xiàng)不起任何作用。
如：option java_outer_classname = "Ponycopter";
?
注：主要是因?yàn)镴ava中要求同一個(gè).java文件中只能包含一個(gè)Java外部類或外部接口，而C++則不存在此限制。因此在.proto文件中定義的消息均為
指定外部類的內(nèi)部類，這樣才能將這些消息生成到同一個(gè)Java文件中。在實(shí)際的使用中，為了避免總是輸入該外部類限定符，可以將該外部類靜態(tài)
引入到當(dāng)前Java文件中，
如：import static com.company.project.LYPhoneMessage.*。
?
四. 注意事項(xiàng)
1）關(guān)于import
protobuf 接口文件可以像C語言的h文件一個(gè)，分離為多個(gè)，在需要的時(shí)候通過 import導(dǎo)入需要對文件。其行為和C語言的#include或者java的import的行為大致相同。
2）關(guān)于package
避免名稱沖突，可以給每個(gè)文件指定一個(gè)package名稱，對于java解析為java中的包。對于C++則解析為名稱空間。
3）關(guān)于message
支持嵌套消息，消息可以包含另一個(gè)消息作為其字段。也可以在消息內(nèi)定義一個(gè)新的消息。
關(guān)于enum
枚舉的定義和C++相同，但是有一些限制。
枚舉值必須大于等于0的整數(shù)。
使用分號(hào)(;)分隔枚舉變量而不是C++語言中的逗號(hào)(,)
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就會(huì)報(bào)錯(cuò)；
?
2、生成C#的.cs文件，使用的是protogen.exe工具，
生成Java，C#，Python文件，使用的是protoc.exe工具；
?
3、生成C#的.cs文件，定義proto文件的message消息時(shí)，變量前面必須添加修飾符：required\optional\repeated，否則報(bào)錯(cuò)；
生成Java，C#，Python文件，，定義proto文件的message消息時(shí)，變量前面不能添加修飾符，否則報(bào)錯(cuò)；
?
?
?
?
總結(jié)
以上是生活随笔為你收集整理的Protobuf之proto文件编写规则的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： Asp.NetCore-部署到IIS
- 下一篇： 程序员de私活攻略