Google API設計指南－命名約定

翻譯自 API Design Guide - Naming Conventions

爲了在長期和大量使用的 API 中提供統一的開發體驗，API 中的全部名字 應該（should） :

• 簡單

• 直觀

• 一致

此文章討論了接口、資源、集合、方法和消息的名字。

由於不少開發者的母語並非英語，這些命名約定經過鼓勵使用簡單、統一的短詞彙來命名方法和資源來保證大部分開發者可以容易理解 API。

• API 中的名字 應該（should） 使用美式英語，例如：license（不是 licence），color（不是 colour）。

• 使用經常使用的簡短形式或縮寫，例如： API 比 Application Programming Interface 更好。

• 儘可能使用直接、熟悉的術語，例如：描述對資源的刪除（銷燬）時，delete 比 erase 更好。

• 對相同的概念使用相同的名字或術語，包括在 API 中共享的概念。

• 避免名字重用，對不一樣的概念要使用不一樣名字。

• 避免使用在 API 上下文中會形成混亂的過於通用的名字，它們會致使對 API 概念的誤解。應該選擇可以精確描述概念的名字。這對於定義一階 API 元素的名稱尤爲重要。由於名字與上下文相關，因此並無明確的名字黑名單。Instance, info 和 service 是會產生問題的名字。應該選擇可以明確表達出 API 概念（例：instance 表示什麼的實例？）而且容易與其餘相關概念有區分（例：alert 的意思是規則，信號仍是通知？）的名字。

• 謹慎使用會與經常使用編程語言中的關鍵字有衝突的名字。

產品名

產品名是指 API 的產品營銷名稱，例如 Google Calendar API。在 API、UI、文檔、服務條款、結帳單和商業合同中使用的產品名稱 應該（should） 一致。

Google API 必須（must） 使用 Google 做爲產品名的前綴，除非它們像 Gmail, Nest, Youtube 這種有不一樣的品牌。通常來講產品名 應該（should） 由產品和市場部門決定。

下表列出了全部相關 API 名稱及其一致性的示例，有關各自名稱及其約定的更多詳細信息，請繼續往下看。

| API 名 | 示例 |
| - | - |
| 產品名 | Google Calendar API |
| 服務名 | calendar.googleapis.com |
| 包名 | google.calendar.v3 |
| 接口名 | google.calendar.v3.CalendarService |
| 資源目錄 | //google/calendar/v3 |
| API 名 | calendar |

服務名

服務名 應該（should） 是一個可以被解析爲一個或多個網絡地址的合法 DNS 名字。公有 Google API 的服務名遵循以下模式：xxx.googleapis.com。例如：谷歌日曆的服務名是 calendar.googleapis.com。

若是一個 API 由多個服務組成，它們 應該（should） 以可以提升可發現性的方法命名。一種方法是爲這些服務名使用相同的前綴。例如服務 build.googleapis.com 和 buildresults.googleapis.com 都是 Google Build API 的一部分。

包名

在 .proto 文件中定義的包名 應該（should） 與產品名和服務名相同。有版本號的包名 必須（must） 以版本號結尾。例如：

// Google Calendar API
package google.calendar.v3;

不與服務直接關聯的抽象 API，例如 Google Watcher API 應該（should） 使用與產品名相同的 proto 包名：

// Google Watcher API
package google.watcher.v1;

在 .proto 文件中指定的 Java 包名 必須（must） 符合標準 Java 包名的前綴（com., edu., net. 等）。例如：

package google.calendar.v3;

// 指定 Java 包的名字，使用標準前綴 "com."
option java_package = "com.google.calendar.v3";

集合 ID

集合 ID 應該（should） 使用美式英語的、複數形式的、首字母小寫的駝峯命名法，例如：events, children 或 deletedEvents。

接口名

爲了不和形如 pubsub.googleapis.com 的資源名混淆，術語 接口名 指的是在 .proto 文件中定義 service 時使用的名字：

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

你能夠認爲 服務名 是指一組 API 的具體實現，接口名 是指一個 API 的抽象定義。

接口名稱 應該（should） 使用直觀的名詞，如 Calendar 或 Blob。不該該（should not） 與編程語言中已有的任何概念或運行時庫衝突（如：File）。

當 接口名 與 API 中其餘名字衝突時，應該爲其加上前綴（如 Api 或 Service）來進行區分。

方法名

在其 IDL 規範中，服務 能夠（may） 定義與集合和資源上的方法相對應的一個或多個RPC方法。方法名 應該（should） 遵循像 VerbNoun 這樣首字母大寫的駝峯命名法的命名約定，其中名詞（Noun）一般是資源類型。

| 動詞（Verb） | 名詞（Noun） | 方法名 | 請求信息 | 響應信息 |
| -| -| - | - | - |
| List | Book | ListBooks | ListBooksRequest | ListBooksResponse |
| Get | Book | GetBook | GetBookRequest | Book |
| Create | Book | CreateBook | CreateBookRequest | Book |
| Update | Book | UpdateBook | UpdateBookRequest | Book |
| Rename | Book | RenameBook | RenameBookRequest | RenameBookResponse |
| Delete | Book | DeleteBook | DeleteBookRequest | google.protobuf.Empty |

消息名

RPC 方法的請求與響應消息 應該（should） 以方法名分別加上 Request 和 Response 的方式命名。除非方法的請求或響應類型以下：

• 空消息（使用 google.protobuf.Empty）

• 資源類型

• 表明一種操做的資源

枚舉名

枚舉類型的名字 必須（must） 使用首字母大寫的駝峯命名法。

枚舉值 必須（must） 如下劃線分隔且字母所有大寫的方式來命名（例如：CAPITALIZED_NAMES_WITH_UNDERSCORES）。每一個枚舉值 必須（must） 以分號而不是逗號結尾。第一個值 應該（should） 命名爲 ENUM_TYPE_UNSPECIFIED，用於當沒有明確指定枚舉值時返回。

enum FooBar {
  // 第一個表示默認值，而且必定等於 0
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

字段名

在 .proto 文件中定義的字段名 必須（must） 如下劃線分隔且字母所有小寫的方式來命名（例如：lower_case_underscore_separated_names）。這些名字會遵照各編程語言的命名約定來映射到生成的代碼中。

重複字段名（Repeated field）

API 中的重複字段 必須（must） 使用合適的複數形式。這符合現有 Google API 的慣例以及外部開發人員的一般指望。

時間和間隔

應該（should） 使用 google.protobuf.Timestamp而且字段名 應該（should） 以 time 結尾來表示獨立於任一時區的時間點。例如 start_time, end_time。

若是表示一個活動的時間，字段名 應該（should） 使用 verb_time 格式，如 create_time, update_time。避免使用動詞的過去時形式，如 created_time 或 last_updated_time。

應該（should） 使用 google.protobuf.Duration 來表示一個時間段。

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

若是由於遺留系統或兼容緣由要使用整形來表示時間相關的字段（包含牆上時間、時間段、延遲），字段名 必須（must） 有以下形式：

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

若是由於遺留系統或兼容緣由要使用字符串來表示時間戳，字段名 不該該（should not） 包含任何單位後綴。應該（should） 使用形如 2014-07-30T10:43:17Z 的 RFC 3339 格式。

日期與時間

應該（should） 使用 google.type.Date 而且字段名以 _date 結尾來表示獨立於時區與時間的日期。若是必須以字符串表示，應該使用形如 YYYY-MM-DD 的 ISO 8601 日期格式（例如 2014-07-30）。

應該（should） 使用 google.type.TimeOfDay 而且字段名以 _time 結尾來表示獨立於時區與日期的時間。若是必須以字符串表示，應該使用形如 HH:MM:SS[.FFF] 的 ISO 8601 的 24 小時時間格式（例如 14:55:01.672）。

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

數量

以整形表示的數量 必須（must） 包含單位。

xxx_{bytes|width_pixels|meters}

若是表示物品的數量，字段名 應該（should） 使用 _count 作爲後綴，如 node_count。

List 過濾字段

若是 List 方法支持過濾資源，包含過濾表達式的字段 應該（should） 命名爲 filter。例：

message ListBooksRequest {
  // 父資源名
  string parent = 1;

  // 過濾表達式
  string filter = 2;
}

List 響應

List 方法的響應消息中包含資源列表的字段名字 必須（must） 是資源名的複數形式。例如，方法 CalendarApi.ListEvents() 必須（must） 定義響應消息 ListEventsResponse，此消息中包含名爲 events 的重複字段來用於返回資源列表。

service CalendarApi {
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=calendars/*}/events";
    };
  }
}

message ListEventsRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventsResponse {
  repeated Event events = 1;
  string next_page_token = 2;
}

駝峯命名法

除了字段名和枚舉值，在 .proto 文件中的全部定義 必須（must） 使用首字母大寫的駝峯命名法。

名字縮寫

對於像 config 和 spec 這種被軟件工程師熟知的縮寫，在 API 定義中 應該（should） 使用縮寫而不是其完整形式，這會使代碼便於讀寫。在正式的文檔中 應該（should） 使用其完整形式。例如：

• config (configuration)

• id (identifier)

• spec (specification)

• stats (statistics)

查看其餘章節