命名规则 - 谷歌API 设计指南 - Tehub

为了能够长时间在众多 API 中为开发者提供一致的体验，API 使用的所有名称都应该具有以下特点：

简单
直观
一致

这包括接口、资源、集合、方法和消息的名称。由于很多开发者不是以英语为母语，所以这些命名惯例的目标之一是确保大多数开发者可以轻松理解 API。对于方法和资源，我们鼓励使用简单、一致和少量的词汇来命名。

API 中使用的名称应采用正确的美式英语。例如，使用美式英语的 license、color，而非英式英语的 licence、colour。
为了简化命名，可以使用已被广泛接受的简写形式或缩写。例如，API 优于 Application Programming Interface。
尽量使用直观、熟悉的术语。例如，如果描述移除（和销毁）一个资源，则删除优于擦除。
使用相同的名称或术语命名同样的概念，包括跨 API 共享的概念。
避免名称过载。使用不同的名称命名不同的概念。
避免在 API 的上下文以及范围更大的 Google API 生态系统中使用含糊不清、过于笼统的名称。这些名称可能导致对 API 概念的误解。相反，应选择能准确描述 API 概念的名称。这对定义一阶 API 元素（例如资源）的名称尤其重要。没有需避免名称的明确列表，因为每个名称都必须放在其他名称的上下文中进行评估。实例、信息和服务的名称都曾出现过这类问题。所选择的名称应清楚地描述 API 概念（例如：什么的实例？），并将其与其他相关概念区分开（例如：“alert”是指规则、信号还是通知？）。
仔细考虑使用的名称是否可能与常用编程语言中的关键字存在冲突。您可以使用这些名称，但在 API 审核期间可能会触发额外的审查。因此应明智而审慎地使用。

产品名称

产品名称是指 API 的产品营销名称，例如 Google Calendar API。API、界面、文档、服务条款、对帐单和商业合同等信息中使用的产品名称必须一致。Google API 必须使用产品团队和营销团队批准的产品名称。下表显示了所有相关 API 名称及其一致性的示例。如需详细了解各自名称及其命名惯例，请参阅本页面下方的详细信息。

API 名称	示例
产品名称	`Google Calendar API`
服务名称	`calendar.googleapis.com`
软件包名称	`google.calendar.v3`
接口名称	`google.calendar.v3.CalendarService`
来源目录	`//google/calendar/v3`
API 名称	`calendar`

服务名称

服务名称应该是语法上有效的 DNS 名称（遵循 RFC 1035），可以解析为一个或多个网络地址。公开的 Google API 的服务名称采用 xxx.googleapis.com 格式。例如，Google 日历的服务名称是 calendar.googleapis.com。如果一个 API 是由多项服务组成，则应采用更容易发现的命名方式。要做到这点，一种方法是使服务名称共享一个通用前缀。例如，build.googleapis.com 和 buildresults.googleapis.com 服务都属于 Google Build API。

软件包名称

API .proto 文件中声明的软件包名称应该与产品名称和服务名称保持一致。软件包名称应该使用单数组件名称，以避免混合使用单数和复数组件名称。软件包名称不能使用下划线。进行版本控制的 API 的软件包名称必须以此版本结尾。例如：

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

与服务无直接关联的抽象 API（例如 Google Watcher API）应该使用与产品名称一致的 proto 软件包名称：

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

API .proto 文件中指定的 Java 软件包名称必须与带有标准 Java 软件包名称前缀（com.、edu.、net. 等）的 proto 软件包名称相匹配。例如：

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

集合 ID

集合 ID 应采用复数和 lowerCamelCase（小驼峰式命名法）格式，并遵循美式英语拼写和语义。例如：events、children 或 deletedEvents。

接口名称

为了避免与服务名称（例如 pubsub.googleapis.com）混淆，术语 *“接口名称”*是指在 .proto 文件中定义 service 时使用的名称：

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

您可以将服务名称视为对一组 API 实际实现的引用，而接口名称则是 API 的抽象定义。接口名称应该使用直观的名词，例如 Calendar 或 Blob。该名称不得与编程语言及其运行时库（如 File）中的成熟概念相冲突。在极少数情况下，接口名称会与 API 中的其他名称相冲突，此时应该使用后缀（例如 Api 或 Service）来消除歧义。

方法名称

服务可以在其 IDL 规范中定义一个或多个远程过程调用 (RPC) 方法，这些方法需与集合和资源上的方法对应。方法名称应采用大驼峰式命名格式并遵循 VerbNoun 的命名惯例，其中 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`

方法名称的动词部分应该使用用于要求或命令的祈使语气，而不是用于提问的陈述语气。对于标准方法，方法名称的名词部分对于除 List 之外的所有方法必须采用单数形式，而对于 List 必须采用复数形式。对于自定义方法，名词在适当情况下可以采用单数或复数形式。批处理方法必须采用复数名词形式。注意：上面的情况指的是协议缓冲区中的 RPC 名称；HTTP/JSON URI 后缀使用 :lowerCamelCase。如果关于 API 子资源的方法名称使用提问动词（经常使用陈述语气表示），则容易让人混淆。例如，要求 API 创建一本书，这显然是 CreateBook（祈使语气），但是询问 API 关于图书发行商的状态可能会使用陈述语气，例如 IsBookPublisherApproved 或 NeedsPublisherApproval。若要在此类情况下继续使用祈使语气，请使用“check”(CheckBookPublisherApproved) 和“validate”(ValidateBookPublisher) 等命令。方法名称不应包含介词（例如“For”、“With”、“At”、“To”）。通常，带有介词的方法名称表示正在使用新方法，应将一个字段添加到现有方法中，或者该方法应使用不同的动词。例如，如果 CreateBook 消息已存在且您正在考虑添加 CreateBookFromDictation，请考虑使用 TranscribeBook 方法。

消息名称

消息名称应该简洁明了。避免不必要或多余的字词。如果不存在无形容词的相应消息，则通常可以省略形容词。例如，如果没有非共享代理设置，则 SharedProxySettings 中的 Shared 是多余的。消息名称不应包含介词（例如“With”、“For”）。通常，带有介词的消息名称可以通过消息上的可选字段来更好地表示。

请求和响应消息

RPC 方法的请求和响应消息应该分别以带有后缀 Request 和 Response 的方法名称命名，除非方法请求或响应类型为以下类型：

一条空消息（使用 google.protobuf.Empty）、
一个资源类型，或
一个表示操作的资源

这通常适用于在标准方法 Get、Create、Update 或 Delete 中使用的请求或响应。

枚举名称

枚举类型必须使用 UpperCamelCase 格式的名称。枚举值必须使用 CAPITALIZED_NAMES_WITH_UNDERSCORES 格式。每个枚举值必须以分号（而不是逗号）结尾。第一个值应该命名为 ENUM_TYPE_UNSPECIFIED，因为在枚举值未明确指定时系统会返回此值。

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

封装容器

封装 proto2 枚举类型（其中 0 值具有非 UNSPECIFIED 的含义）的消息应该以后缀 Value 来命名，并具有名为 value 的单个字段。

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

字段名称

.proto 文件中的字段定义必须使用 lower_case_underscore_separated_names 格式。这些名称将映射到每种编程语言的生成代码中的原生命名惯例。字段名称不应包含介词（例如“for”、“during”、“at”），例如：

reason_for_error 应该改成 error_reason
cpu_usage_at_time_of_failure 应该改成 failure_time_cpu_usage

字段名称不应使用后置形容词（名词后面的修饰符），例如：

items_collected 应该改成 collected_items
objects_imported 应该改成 imported_objects

重复字段名称

API 中的重复字段必须使用正确的复数形式。这符合现有 Google API 的命名惯例和外部开发者的共同预期。

时间和时间段

要表示一个与任何时区或日历无关的时间点，应该使用 google.protobuf.Timestamp，并且字段名称应该以 time（例如 start_time 和 end_time）结尾。如果时间指向一个活动，则字段名称应该采用 verb_time 的形式，例如 create_time 和 update_time。请勿使用动词的过去时态，例如 created_time 或 last_updated_time。要表示与任何日历和概念（如“天”或“月”）无关的两个时间点之间的时间跨度，应该使用 google.protobuf.Duration。

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

如果由于历史性或兼容性原因（包括系统时间、时长、推迟和延迟），您必须使用整数类型表示与时间相关的字段，那么字段名称必须采用以下格式：

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

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

如果由于历史性或兼容性原因，您必须使用字符串类型表示时间戳，则字段名称不应该包含任何单位后缀。字符串表示形式应该使用 RFC 3339 格式，例如“2014-07-30T10:43:17Z”。

日期和时间

对于与时区和时段无关的日期，应该使用 google.type.Date，并且该名称应具有后缀 _date。如果日期必须表示为字符串，则应采用 ISO 8601 日期格式 YYYY-MM-DD，例如 2014-07-30。对于与时区和日期无关的时间，应该使用 google.type.TimeOfDay，并且该名称应具有后缀 _time。如果时间必须表示为字符串，则应采用 ISO 8601 24 小时制格式 HH:MM:SS[.FFF]，例如 14:55:01.672。

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

数量

由整数类型表示的数量必须包含度量单位。

xxx_{bytes|width_pixels|meters}

如果数量是条目计数，则该字段应该具有后缀 _count，例如 node_count。

列表过滤器字段

如果 API 支持对 List 方法返回的资源进行过滤，则包含过滤器表达式的字段应该命名为 filter。例如：

message ListBooksRequest {
  // The parent resource name.
  string parent = 1;

  // The filter expression.
  string filter = 2;
}

列表响应

List 方法的响应消息（包含资源列表）中的字段名称必须是资源名称本身的复数形式。例如，CalendarApi.ListEvents() 方法必须为返回的资源列表定义一个响应消息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 文件中的所有定义都必须使用由 Google Java 样式定义的 UpperCamelCase 格式的名称。

名称缩写

对于软件开发者熟知的名称缩写，例如 config 和 spec，应该在 API 定义中使用这些缩写，而非完整名称。这将使源代码易于读写。而在正式文档中，应该使用完整名称。示例：

config (configuration)
id (identifier)
spec (specification)
stats (statistics)