風格指南

提供如何最佳架構您的 proto 定義的指引。

此文件提供 .proto 檔案的風格指南。透過遵循這些慣例，您將使您的 Protocol Buffer 訊息定義及其對應的類別保持一致且易於閱讀。

請注意，Protocol Buffer 的風格會隨著時間演變，因此您可能會看到以不同慣例或風格撰寫的 .proto 檔案。當您修改這些檔案時，請尊重現有的風格。一致性是關鍵。然而，當您建立新的 .proto 檔案時，最好採用當前最佳風格。

標準檔案格式

將行長度保持在 80 個字元。
使用 2 個空格的縮排。
字串偏好使用雙引號。

檔案結構

檔案應命名為 lower_snake_case.proto。

所有檔案都應按以下順序排列

授權標頭（如果適用）
檔案概述
語法
套件
匯入（已排序）
檔案選項
其他所有內容

套件

套件名稱應為小寫。套件名稱應根據專案名稱，並可能根據包含 Protocol Buffer 類型定義的檔案路徑，擁有唯一名稱。

訊息和欄位名稱

訊息名稱使用 PascalCase（首字母大寫）：SongServerRequest。縮寫字偏好視為單字並大寫：GetDnsRequest 而非 GetDNSRequest。欄位名稱使用 lower_snake_case，包括 oneof 欄位和擴展名稱：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;

列舉

列舉類型名稱使用 PascalCase（首字母大寫），值名稱使用 CAPITALS_WITH_UNDERSCORES

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

每個列舉值都應以分號結尾，而不是逗號。偏好為列舉值加上前綴，而不是將它們包圍在一個封閉的訊息中。由於某些語言不支援在「結構」類型內定義列舉，因此這確保了跨繫結語言的一致方法。

零值列舉應具有 UNSPECIFIED 後綴，因為伺服器或應用程式若收到非預期的列舉值，將會在 proto 實例中將該欄位標記為未設定。然後，欄位存取器將傳回預設值，對於列舉欄位而言，預設值為第一個列舉值。有關未指定列舉值的更多資訊，請參閱Proto 最佳實務頁面。

服務

如果您的 .proto 定義了 RPC 服務，則服務名稱和任何 RPC 方法名稱都應使用 PascalCase（首字母大寫）

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

有關更多服務相關指引，請參閱 API 最佳實務主題中的針對每個方法建立唯一的 Proto 和請勿在頂層請求或回應 Proto 中包含基本類型，以及 Proto 最佳實務中的在單獨檔案中定義訊息。

應避免的事項

必要欄位（僅適用於 proto2）
群組（僅適用於 proto2）