AIP-123 资源类型

编号	123
原文链接	AIP-123: Resource types
状态	批准
创建日期	2019-05-12
更新日期	2019-05-12

大多数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 ：完善示例中的注解。