注意:這個網站已不適用。網站將在 2023 年 1 月 31 日後關閉,而流量會重新導向至 https://protobuf.dev。在此同時,系統只會將資料更新至 protobuf.dev。

樣式指南

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本文件提供 .proto 檔案的樣式指南。只要遵循這些慣例,您的通訊協定緩衝區訊息定義和對應的類別就會一致且易於閱讀。

請注意,通訊協定緩衝區樣式會隨著時間改變,因此您可能會看見以不同慣例或樣式編寫的 .proto 檔案。修改這些檔案時,請遵守現有的樣式一致性是關鍵。不過,建議您在建立新的 .proto 檔案時,採用目前的最佳樣式。

標準檔案格式

  • 長度上限為 80 個半形字元。
  • 使用 2 個空格的縮排。
  • 最好在字串中使用雙引號。

檔案結構

檔案名稱應為 lower_snake_case.proto

所有檔案的排序方式如下:

  1. 授權標頭 (如適用)
  2. 檔案總覽
  3. 語法
  4. 包裝
  5. 匯入 (已排序)
  6. 檔案選項
  7. 其他

包裹

套件名稱應使用小寫。套件名稱應根據專案名稱使用不同名稱,而且可能取決於包含通訊協定緩衝區類型定義的檔案路徑。

訊息和欄位名稱

使用 CamelCase (含首字母大寫) 做為訊息名稱,例如 SongServerRequest。為欄位名稱 (包括其中一個欄位和擴充功能名稱) 使用 Underscore_split_names,例如 song_name

message SongServerRequest {
  optional string song_name = 1;
}

按照此命名慣例為欄位名稱提供以下存取子元件:

C++:
  const string& song_name() { ... }
  void set_song_name(const string& x) { ... }

Java:
  public String getSongName() { ... }
  public Builder setSongName(String v) { ... }

如果你的欄位名稱包含數字,該數字應出現在字母後方,而非底線下方。例如,使用 song_name1 而不是 song_name_1

重複欄位

在重複欄位中使用多組名稱。

  repeated string keys = 1;
  ...
  repeated MyMessage accounts = 17;

列舉

使用 CamelCase (含首字母大寫) 做為列舉類型名稱,並使用 CAPITALS_WITH_ERSDRES 做為值名稱:

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}

每個列舉值應以半形分號 (而非逗號) 結尾。最好為前置字串值加上前置字元,而不要在封閉式訊息中包圍這些值。零值列舉應具有後置字串 UNSPECIFIED,因為在取得 proto 執行個體時,會取得非預期的列舉值的伺服器或應用程式會將該欄位標示為未設定。欄位存取子接著會傳回預設值,對列舉欄位而言,此屬性為第一個列舉值。

服務

如果您的 .proto 定義了遠端程序呼叫 (RPC) 服務,請針對服務名稱和任何遠端程序呼叫 (RPC) 方法名稱使用 CamelCase (含首字母大寫):

service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}

應避免的事項

  • 必填欄位 (僅適用於 proto2)
  • 群組 (僅適用於 proto2)