定義一個 Message 類型
假設您要定義 search request message 格式漓拾，其中每個搜索請求都有一個查詢字符串倔韭、您感興趣的特定結果頁面贝奇、每頁的結果數(shù)量航棱。
這是用于定義消息類型的 .proto 文件睡雇。
syntax = "proto3";
message SearchRequest {
string query = 1;
int32 page_number = 2;
int32 result_per_page = 3;
}
- 該文件的第一行指定您使用的是 proto3 語法：如果您不這樣做，protocol buffer 編譯器將假定您使用的是 proto2饮醇。 這必須是文件的第一個非空它抱、非注釋行。
- SearchRequest 消息定義指定了三個字段（名稱/值對）朴艰，每個字段用于您希望包含在此類消息中的每條數(shù)據(jù)观蓄。 每個字段都有一個名稱和一個類型混移。
指定字段類型
在上面的示例中，所有字段都是標量類型：兩個整數(shù)（page_number 和 result_per_page）和一個字符串（query）侮穿。
但是歌径，您也可以為字段指定復合類型，包括枚舉和其他消息類型亲茅。
分配字段編號
如您所見沮脖，消息定義中的每個字段都有一個唯一編號。 這些字段編號用于以消息二進制格式標識您的字段芯急，一旦使用您的消息類型就不應更改勺届。
請注意，1 到 15 范圍內(nèi)的字段編號需要一個字節(jié)進行編碼娶耍，包括字段編號和字段類型（您可以在 Protocol Buffer Encoding 中找到更多相關信息）免姿。
16 到 2047 范圍內(nèi)的字段編號占用兩個字節(jié)。
因此榕酒，您應該為非常頻繁出現(xiàn)的消息元素保留數(shù)字 1 到 15胚膊。 請記住為將來可能添加的頻繁出現(xiàn)的元素留出一些空間。
可以指定的最小字段編號是 1想鹰，最大的是 2^29 - 1紊婉，即 536,870,911。
您也不能使用數(shù)字 19000 到 19999（FieldDescriptor::kFirstReservedNumber 到 FieldDescriptor::kLastReservedNumber）辑舷，因為它們是為 protocol
buffer 實現(xiàn)保留的喻犁。如果您在 .proto 中使用這些保留數(shù)字之一，編譯器會報錯何缓。 同樣肢础，您不能使用任何以前保留的字段編號。
指定字段規(guī)則
消息字段可以是以下之一：
- singular
格式良好的 message 可以包含零個或一個此字段（但不超過一個）碌廓。
這是 proto3 語法的默認字段規(guī)則传轰。 - repeated
格式良好的 message 中，此字段可以重復任意次數(shù)（包括零次）谷婆。
重復值的順序?qū)⒈槐Ａ簟?/li>
添加更多消息類型
可以在單個 .proto 文件中定義多種 message 類型慨蛙。 如果您要定義多個相關message，這很有用纪挎。
例如期贫，如果您想定義與您的 SearchResponse 消息類型，相對應的回復消息格式廷区，您可以將其添加到同一個 .proto 中：
message SearchRequest {
string query = 1;
int32 page_number = 2;
int32 result_per_page = 3;
}
message SearchResponse {
...
}
添加注釋
To add comments to your .proto files, use C/C++-style // and /* ... */ syntax.
/* SearchRequest represents a search query, with pagination options to
* indicate which results to include in the response. */
message SearchRequest {
string query = 1;
int32 page_number = 2; // Which page number do we want?
int32 result_per_page = 3; // Number of results to return per page.
}
保留字段
如果您通過 完全刪除某個字段 或 將其注釋掉 來更新消息類型唯灵，未來的用戶可以在對類型進行自己的更新時重用該字段編號。
如果他們稍后加載相同 .proto 的舊版本隙轻，這可能會導致嚴重的問題埠帕，包括數(shù)據(jù)損壞、隱私錯誤等玖绿。
確保不會發(fā)生這種情況的一種方法是指定保留已刪除字段的字段編號（和/或名稱敛瓷，這也可能導致 JSON 序列化問題）。
如果將來有任何用戶嘗試使用這些字段標識符斑匪，protocol buffer 編譯器會抱怨呐籽。
message Foo {
reserved 2, 15, 9 to 11;
reserved "foo", "bar";
}
請注意，您不能在同一保留語句中混合字段名稱和字段編號蚀瘸。
你的 .proto 生成了什么狡蝶？
For Go, the compiler generates a .pb.go file with a type for each message type in your file.
