定義一個 Message 類型
假設您要定義 search request message 格式，其中每個搜索請求都有一個查詢字符串、您感興趣的特定結(jié)果頁面、每頁的結(jié)果數(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.
