AIP-123 资源类型

大多数API发布了用户可以创建、获取和操作的 资源 （主要是名词）。API可以合理的、自由的命名资源类型（在AIP要求的范围内），只要保证在API内的唯一性。这意味着不同API可能（需要）使用相同的类型名字。例如Memcache和Redis API都希望使用 Instance 作为类型名字。

然而在将API和资源关联起来时，拥有全局唯一的类型名字变得非常重要。此外，像Kubernetes或GraphQL这样的工具需要与来自多个供应商的API进行交互。

术语

在下面的指南中，我们使用以下术语：

• 服务名字 ：在服务配置中定义的名字。这通常（但不一定）与用户调用服务的主机名（例如 pubsub.googleapis.com ）一致 。它相当于Kubernetes中的API组。
• 类型 ：在API中的类型名字，例如protobuf消息的名字。相当于Kubernetes中的对象。

指南

API 必须 为每个资源定义资源类型，并遵从模式 {服务名字}/{类型} 。类型名字 必须 满足：

• 与所属API类型名字一致。
• 以大写字母开头。
• 只包含字母和数字。
• 使用名词单数形式。
• 使用PascalCase（UpperCamelCase）风格。

示例

资源类型的例子包括：

• pubsub.googleapis.com/Topic
• pubsub.googleapis.com/Subscription
• spanner.googleapis.com/Database
• spanner.googleapis.com/Instance
• networking.istio.io/Instance

资源类型注解

API 应当 使用 google.api.resource 作为每个资源类型的注解：

// A representation of a Pub/Sub topic.
message Topic {
  option (google.api.resource) = {
    type: "pubsub.googleapis.com/Topic"
    pattern: "projects/{project}/topics/{topic}"
    singular: "topic"
    plural: "topics"
  };

  // Name and other fields...
}

• 模式 必须 与资源名字相对应。
• 模式变量（大括号内的段） 必须 使用 snake_case ，且 不得 使用 _id 后缀。
• 模式变量 必须 符合格式 [a-z][_a-z0-9]*[a-z0-9] 。
• 模式变量 必须 在模式内只出现一次。（例如 projects/{abc}/topics/{abc} 是无效的，这是要求标识符只出现一次的必然结论。）
• 使用多模式的资源 必须 保持顺序：新模式 必须 添加到列表末尾，现有模式 不得 删除或重新排列，避免破坏客户端库的向后兼容性。
• 单数 必须 是类型的camelCase。
  • 模式变量 必须 是资源类型的单数形式，例如表示 Topic 资源标识的模式变量名为 {topic} 。
• 复数 必须 是单数（camelCase）的复数形式。
  • 模式集合标识符段 必须 与资源的复数形式一致，内嵌集合除外。

模式唯一性

如果资源定义了多个模式，这些模式 必须 相互唯一，唯一性定义为在删除所有资源标识路径段，留下所有分隔符（ / ）后，字符完全相同。

因此，以下两个模式 不得 在同一资源中使用：

• user/{user}
• user/{user_part_1}~{user_part_2}

理由

类型和消息名字对齐

除了简单的模式-资源一致性对齐之外，许多消费者还受益于类型和消息名字一致性。消费者查找起来更简单，客户端库也一样，而且还能带来用户体验一致性，因为面向资源的代码与生成的消息代码的名字是对齐的，生成的参考文档和资源消息文档也是对齐的……

单数和复数

明确定义资源的单数和复数形式，可以让客户端确认在代码和文档中应当使用的正确拼写。

camelCase可以转换为其他常见的资源名字风格，如PascalCase和snake_case。

修订记录

• 2025-01-09 ：对齐资源类型和消息名字。
• 2024-08-07 ：添加多模式顺序兼容性要求。
• 2023-09-19 ：禁止模式变量重复。
• 2023-05-06 ：添加单数和复数要求。
• 2023-01-28 ：明确资源类型名字指南。
• 2022-10-28 ：添加模式变量格式指南。
• 2020-05-14 ：添加模式唯一性要求。
• 2019-12-05 ：添加模式指南。
• 2019-07-17 ：完善示例中的注解。