AIP-140

Field names

Naming fields in a way that is intuitive to users can often be one of the most challenging aspects of designing an API. This is true for many reasons; often a field name that seems entirely intuitive to the author can baffle a reader. 在设计API的挑战性方面，以用户直观的方式命名字段通常是最直观的方式之一。由于许多原因，情况确实如此。 通常对作者来说完全直观的字段名称可能会让读者感到困惑。

Additionally, users rarely use only one API; they use many APIs together. As a result, a single company using the same name to mean different things (or different names to mean the same thing) can often cause unnecessary confusion, because users can no longer take what they've already learned from one API and apply that to another. 此外，用户很少只使用一个API。它们同时使用许多 API。作为结果，单个公司使用相同的名称来表示不同的东西（或 不同的名称表示相同的东西）往往会引起不必要的混淆，因为用户无法再从一个 API 中获取他们已经学到的知识，并且 将其应用于另一个。

In short, APIs are easiest to understand when field names are simple, intuitive, and consistent with one another. 简而言之，当字段名称简单时，API 最容易理解，直观，并且彼此一致。

Guidance

Field names should be in correct American English. 字段名称 应为正确的美式英语。

Field names should clearly and precisely communicate the concept being presented and avoid overly general names that are ambiguous. That said, field names should avoid including unnecessary words. In particular, avoid including adjectives that always apply and add little cognitive value. For example, a proxy_settings field might be as helpful as shared_proxy_settings if there is no unshared variant.　 字段名称应该清晰准确地传达概念呈现并避免过于笼统且模棱两可的名称。也就是说，字段 名称应避免包含不必要的单词。例如，如果有共享的变体则"shared_proxy_settings"比"proxy_settings"字段可能更有帮助。

Case

Field definitions in protobuf files must use lower_snake_case names. These names are mapped to an appropriate naming convention in JSON and in generated code. protobuf 文件中的字段定义 必须 使用"小蛇式"名称。这些名称映射到JSON和生成的代码。

Additionally, each word in the field must not begin with a number, because it creates ambiguity when converting between snake case and camel case. Similarly, fields must not contain leading, trailing, or adjacent underscores. 此外，字段中的每个单词不得以数字开头，因为在蛇式和骆驼式之间转换时会产生歧义。同样，字段不得包含前导、尾随或相邻强调。

Consistency

APIs should endeavor to use the same name for the same concept and different names for different concepts wherever possible. This includes names across multiple APIs, in particular if those APIs are likely to be used together. API 应该 努力为相同的概念使用相同的名称，并且尽可能为不同的概念使用不同的名称。这包括名称跨多个 API，特别是如果这些 API 可能被使用一起。

Repeated fields

Repeated fields must use the proper plural form, such as books or authors. On the other hand, non-repeated fields should use the singular form such as book or author. This implies that resource names should use the singular form as well, since the field name should follow the resource name (e.g., use repeated Book books, not Books books = 1). 重复字段 必须 使用正确的复数形式,例如books或者authors。另一方面，非重复字段 应 使用单数 形式，如"book"或"author"。这意味着资源名称也 应该 使用单数形式，因为字段名称应跟在资源后面(例如，使用repeated Book books, 而不是 Books books = 1)

Prepositions　介词

Field names should not include prepositions (such as "with", "for", "at", "by", etc). For example: 字段名　不应该　包含介词（例如　"with", "for", "at",　"by", etc). 例如：

  • error_reason (而不是 reason_for_error)
  • author (而不是 written_by)

It is easier for field names to match more often when following this convention. Additionally, prepositions in field names may also indicate a design concern, such as an overly-restrictive field or a sub-optimal data type. This is particularly true regarding "with": a field named book_with_publisher likely indicates that the book resource may be improperly structured and worth redesigning. 遵循此操作时，字段名称更容易更频繁地匹配。此外，字段名称中的介词也可能表示设计问题，例如限制性过强的字段或次优数据类型。 对于"with"尤其如此：一个名为"book_with_publisher"的字段可能表示书籍资源可能结构不当且有价值 重新设计。

Note: The word "per" is an exception to this rule, particularly in two cases. Often "per" is part of a unit (e.g. "miles per hour"), in which case the preposition must be present to accurately convey the unit. Additionally, "per" is often appropriate in reporting scenarios (e.g. "nodes per instance" or "failures per hour").　"per"一词是这一规则的例外，特别是在两种情况下。通常，"per"是单位的一部分（例如"英里/小时"），在这种情况下，必须存在介词才能准确传达单位。此外，"per"通常适用于报告场景（例如，"每个实例的节点数"或"每小时故障数"）。

Adjectives　形容词

For consistency, field names that contain both a noun and an adjective should place the adjective before the noun. For example: 为保持一致，字段名称同时包含名词和形容词应该将形容词放在名词之前。 例如：

  • collected_items (而不是 items_collected)
  • imported_objects (而不是 objects_imported)

Booleans

Boolean fields should omit the prefix "is". For example: 布尔字段应该省略前缀“is”。 例如

  • disabled (而不是 is_disabled)
  • required (而不是 is_required)

Note: Field names that would otherwise be reserved words are an exception to this rule. For example, is_new (not new). 保留字的字段名称是此规则的例外。例如，is_new（不是 new）。

String vs. bytes

When using bytes, the contents of the field are base64-encoded when using JSON on the wire. Services should use bytes when there is a need to send binary contents over the wire, and should not ask the user to manually base64-encode a field into a string field. 使用bytes时，字段的内容在使用时采用base64编码网络上的JSON。 服务应该使用bytes，当需要发送 通过网络传输二进制内容，并且不应要求用户手动base64 - 将字段编码为"字符串"字段。

URIs

Field names representing URLs or URIs should always use uri rather than url. This is because while all URLs are URIs, not all URIs are URLs. Field names may use a prefix in front of uri as appropriate. 表示 URL 或 URI 的字段名称 应 始终使用uri而不是url。这是因为虽然所有 URL 都是 URI，但并非所有 URI 都是 URL。名称 可以 在"uri"前面适当地使用前缀。

Reserved words 保留字

Field names should avoid using names that are likely to conflict with keywords in common programming languages, such as new, class, function, import, etc. Reserved keywords can cause hardship for developers using the API in that language. 字段名称 应 避免使用可能与常用编程语言中的关键字，例如new, class, function, import等保留关键字可能会给使用该语言的 API的开发者造成困难。

Conflicts　冲突

Messages should not include a field with the same name as the enclosing message (ignoring case transformations). This causes conflicts when generating code in some languages.消息 不应 包含与封闭名称相同的字段消息（忽略大小写转换）。这会导致生成时发生冲突某些语言的代码。

Display names　显示名称

Many resources have a human-readable name, often used for display in UI. This field should be called display_name, and should not have a uniqueness requirement. 许多资源具有用户可读的名称，通常用于在 UI 中显示。这字段 应 称为display_name，并且 不应 具有唯一性要求。

If an entity has an official, formal name (such as a company name or the title of a book), an API may use title as the field name instead. The title field should not have a uniqueness requirement. 如果实体具有官方的正式名称（例如公司名称或头衔）），API 可能 使用"头衔"作为字段名称。title字段 不应 具有唯一性要求。

Further reading

  • For naming resource fields, see AIP-122.
  • For naming fields representing quantities, see AIP-141.
  • For naming fields representing time, see AIP-142.

Changelog

  • 2021-07-12: Normalized display name guidance to "should".
  • 2021-04-07: Added base64 and bytes guidance.
  • 2021-03-05: Added prohibition on leading, trailing, or adjacent underscores.
  • 2020-06-10: Added prohibition on starting any word with a number.
  • 2020-05-29: Added guidance around URIs.
  • 2020-03-24: Added guidance around conflicting field and message names.
  • 2020-01-30: Added guidance around display_name and title.