一、引言

本文用來介紹Google的protocol-buffer 訊息的格式以及使用事項，不會涉及相關api的使用

二、訊息定義

訊息由至少一個欄位組合而成，類似於C語言中的結構。每個欄位都有一定的格式 欄位格式：限定修飾符① | 資料型別② | 欄位名稱③ | = | 欄位編碼值④ | [欄位預設值⑤]

1、限定修飾符

限定修飾符包含 required optional repeated

• required 一個格式良好的訊息一定要含有1個這種欄位。表示該值是必須要設定的，必須相對於傳送方，在傳送訊息之前必須設定該欄位的值，對於接收方，必須能夠識別該欄位的意思。傳送之前沒有設定required欄位或者無法識別required欄位都會引發編解碼異常，導致訊息被丟棄，是永久性的：在將一個欄位標識為required的時候，應該特別小心。如果在某些情況下不想寫入或者傳送一個required的 欄位，將原始該欄位修飾符更改為optional可能會遇到問題——舊版本的使用者會認為不含該欄位的訊息是不完整的，從而可能會無目的的拒絕解析。在這 種情況下，你應該考慮編寫特別針對於應用程式的、自定義的訊息校驗函式。Google的一些工程師得出了一個結論：使用required弊多於利；他們更 願意使用optional和repeated而不是required。當然，這個觀點並不具有普遍性。
• optional 訊息格式中該欄位可以有0個或1個值（不超過1個），表示是一個可選欄位，可選對於傳送方，在傳送訊息時，可以有選擇性的設定或者不設定該欄位的值。對於接收方，如果能夠識別可選欄位就進行相應的處理，如果無法識別，則忽略該欄位，訊息中的其它欄位正常處理。—因為optional欄位的特性，很多介面在升級版本中都把後來新增的欄位都統一的設定為optional欄位，這樣老的版本無需升級程式也可以正常的與新的軟體進行通訊，只不過新的欄位無法識別而已，因為並不是每個節點都需要新的功能，因此可以做到按需升級和平滑過渡。
• repeated 這種欄位可以重複任意多次（包括0次）。重複的值的順序會被保留。表示該值可以重複，相當於List

2、基本型別定義

protocol-buffer 基本資料型別

補充說明 N 表示打包的位元組並不是固定。而是根據資料的大小或者長度。例如int32，如果數值比較小，在0~127時，使用一個位元組打包。關於列舉的打包方式和uint32相同。關於 fixed32 和int32的區別。fixed32的打包效率比int32的效率高，但是使用的空間一般比int32多。因此一個屬於時間效率高，一個屬於空間效率高。根據專案的實際情況，一般選擇fixed32，如果遇到對傳輸資料量要求比較苛刻的環境，可以選擇int32.

有關enum message 特說說明

在定義message型別的時候，也許會有這樣一種需求：其中的一個欄位僅需要包含預定義的若干個值即可。比如，對於每一個搜尋請求，現需要增加一個分類欄位，分類包含：UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS or VIDEO。要實現該功能，僅需要增加一個列舉型別欄位。如下：

message SearchRequest {
    required string query = 1;
    optional int32 page_number = 2;
    optional int32 result_per_page = 3 [default = 10];
    enum Corpus {
       UNIVERSAL = 0;
       WEB = 1;
       IMAGES = 2;
       LOCAL = 3;
       NEWS = 4;
       PRODUCTS = 5;
       VIDEO = 6;
    }
    optional Corpus corpus = 4 [default = UNIVERSAL];
}

可以定義列舉在一個message內部,也可以定義在message的外部，這樣的列舉可以被其他任何.proto檔案內的message複用。

使用其他Message型別作為filed型別 PB允許使用message型別作為filed型別。例如，在搜尋相應message中，包含一個結果message。此時，只需要定義一個結果message，然後再.proto檔案中，在搜尋結果message中新增一個欄位，該欄位的型別設定為結果message即可。

message SearchResponse 
{
    repeated Result result = 1;
}

message Result 
{
    required string url = 1;
    optional string title = 2;
    repeated string snippets = 3;
}

在上例中，Result message型別與SearchResponse 定義在同一個檔案中，假如有這麼一種情況，這裡所要使用的Resultmessage已經在其他的.proto檔案中定義了呢？ 可以通過匯入其他.proto檔案來使用其內的定義。為達此目的，需要在現.proto檔案前增加一條import語句：

import "myproject/other_protos.proto";

巢狀型別： Message型別可以巢狀，類似於c++中的巢狀類，可以無限深層次巢狀。

3、欄位名稱

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

4、欄位編碼值

有了該值，通訊雙方才能互相識別對方的欄位。當然相同的編碼值，其限定修飾符和資料型別必須相同。 編碼值的取值範圍為 1~2^32（4294967296）。 其中 1~15的編碼時間和空間效率都是最高的，編碼值越大，其編碼的時間和空間效率就越低（相對於1-15），當然一般情況下相鄰的2個值編碼效率的是相同的，除非2個值恰好實在4位元組，12位元組，20位元組等的臨界區。比如15和16. 1900~2000編碼值為Google protobuf 系統內部保留值，建議不要在自己的專案中使用。 protobuf 還建議把經常要傳遞的值把其欄位編碼設定為1-15之間的值。 訊息中的欄位的編碼值無需連續，只要是合法的，並且不能在同一個訊息中有欄位包含相同的編碼值。 建議：專案投入運營以後涉及到版本升級時的新增訊息欄位全部使用optional或者repeated，儘量不實用required。如果使用了required，需要全網統一升級，如果使用optional或者repeated可以平滑升級。

5、欄位預設值

protocol-buffer 允許設定可選欄位(optional)。顧名思義，在一條message中，該欄位可設值也可不設。假如沒有設定，那麼在解析該欄位的時候，會根據該欄位型別，給其賦一個型別預設值。除此之外，也可以在定義message格式的時候，就為optional欄位設定一個預設值，如下：

optional int32 result_per_page = 3 [default = 10];

假如沒有賦值的話，會被賦上預設值。對於簡單型別，預設值可以自己設定，例如上例的PhoneNumber中的PhoneType欄位。如果沒有自行設定，會被賦上一個系統預設值，數字型別會被賦為0，String型別會被賦為空字串，bool型別會被賦為false。對於列舉型別，預設值是列舉列表中第一個值

三、結束語