AIP-213 通用组件
| 编号 | 213 |
|---|---|
| 原文链接 | AIP-213: Common components |
| 状态 | 批准 |
| 创建日期 | 2018-08-17 |
| 更新日期 | 2018-08-17 |
根据AIP-215规定，除使用“通用组件”包之外，API必须是独立的。通用组件包是给多个API使用的。
通用组件包有两种类型：
- 组织特定的通用组件，包括组织特定的概念，例如地图中的“视口”。
- 全局通用组件，这些组件是通用的（即不特定于某个领域），例如“时间戳”或“邮政地址”。
如果可以安全在多个API之间共享同一个消息，通用组件可以让客户端更容易API交互。例如关于特定概念的客户端代码只需要编写一次，一个API的应答中的消息可以直接用于另一个API的请求，无需低效的复制。
当让这种优势也存在重要的限制和局限性，不应轻易尝试。
请注意，即使组件所属 领域 是通用的，组件也可能是组织特定的。例如某些组织可能对财务值的展示有特定要求，产生多个面向财务的组织特定通用组件——因为全局通用组件要么不符合组织特定要求，要么对于一般用法来说过于复杂。
指南
- 组织范围内的通用组件包 必须 以
.type结尾，例如google.geo.type或google.shopping.type。 - 在创建新的组织范围内通用组件包之前， 必须 咨询API设计团队。
- 组织范围内的通用组件包 必须 发布在 googleapis 仓库。
- 创建和发布新的组织通用组件包后，组织 必须 更新本AIP，在下面的列表中添加新包。
- 组织 不得 在组织特定通用组件包中定义（非特定）通用组件，建议优先使用全局通用组件。
- 通用组件 不得 从组织特定通用组件包“移动”（即从一个通用组件包中删除，再添加到另一个中）到全局通用组件包，或反之。
- 如果发现特定通用组件比最初预期的使用场景更广泛， 可以 将其从组织特定通用组件包复制到全局通用组件包（但不删除原组件）。
- 不应 向现有消息添加域。
- 不应 向现有枚举添加值。
- 不得 从现有消息中删除域。
- 不得 从现有枚举中删除值。
- 虽然 可以 在文档中说明，但 不应 更改现有值的含义，包括任何给定消息或消息集的有效性。
- 可以 向通用组件包添加新proto消息和枚举。
- 在API使用新消息和枚举之前，API团队 应当 留出足够时间进行客户端推广。新域可能需要一些时间，才能通过发布客户端库和其他界面得到推广。
- 由于上述限制，API团队在添加新消息或枚举之前， 应当 广泛征求组织内部意见，适时咨询API设计团队。
现有的全局通用组件
API 可以 安全导入的、公布了proto的全局通用组件如下所示：
- google.api.*（ 不 包括
google.api的子包） - google.longrunning.Operation
- google.protobuf.*
- google.rpc.*
- google.type.*
请注意，某些通用组件可能具有内部域。API通常 应当 仅依赖已开源的域。
Google API也 可以 导入google.iam.v1.*，它提供了在Google中使用的IAM消息。
注意 许多API从其他包导入组件在内部使用（例如应用可见性标签或向内部基础设施提供指令）。只要 公开 组件不包含这些引用，也是可以的。
Protobuf类型
google.protobuf 包有些特殊，它随protocol buffer一起发布，而非随API工具一起发布。（对于大多数API设计者来说，这是实现层面细节）。
这个包拥有一个表示常见编程语言结构的小型库：
- google.protobuf.Duration：时长，精度纳秒。protobuf运行时提供了辅助函数，适时转换成语言本地时长对象（例如Python的 timedelta ）。
- google.protobuf.Struct：类似JSON的结构（基础类型值、列表和嵌套其他字典的字典）。protobuf运行时在大多数语言中都提供了辅助函数，将struct对象和JSON相互转换。
- google.protobuf.Timestamp：时间戳，精度纳秒。protobuf运行时在大多数语言中都提供了辅助函数，与语言本地时间戳对象进行转换（例如Python的 datetime ）。
API类型
google.type 包为 API 中的常见概念提供了一套“标准库”类型。尽管类型会不定期新增且最终权威列表始终以代码为准，但以下几种类型值得特别关注：
google.type 包提供了API中的常见概念类型的“标准库”。类型会不定期增加，定义列表以代码为准。其中有几个类型值得注意：
- google.type.Color：RGB或RGBA颜色。
- google.type.Date：日历日期。不含时间或时区组件。
- google.type.DayOfWeek：星期几。不含其他日期、时间或时区组件。
- google.type.LatLng：地理坐标。
- google.type.Money：货币。
- google.type.PostalAddress：大多数国家的邮政地址。
- google.type.TimeOfDay：挂钟时间。不含日期或时区组件。
新增通用proto
有时可能需要向这些包或公用proto添加proto。请在GitHub上的AIP创建问题，请注意上述指南。
现有组织特定通用组件包
现有以下组织特定通用组件包，均符合上述指南：
- google.apps.script.type Google Apps Script通用组件包。
- google.geo.type Google Maps和Geo的通用组件包。
- google.actions.type Actions on Google API通用组件包。
规则例外通用组件包
现有以下通用组件包不符合上述指南，但不应构成后续类似包的先例。
- google.cloud.common： 不符合包名以.type结尾的要求。（否则不会产生例外。此包应作为Cloud通用组件包。）
- google.logging.type： 虽然被多个API使用，更像是API特定的。其中某些部分可能应放置在全局或Cloud通用组件包。
- google.cloud.workflows.type： API特定类型。
- google.cloud.oslogin.common： API特定类型，以及不符合名字要求。
- google.identity.accesscontextmanager.type： API特定类型。
- google.networking.trafficdirector.type： API特定类型。
理由
通用组件实际上是没有版本控制：API在定义和实现上彼此独立发展。注入添加新域的更改在特定API中是向后兼容和可预测的，API团队可以保证在发布API定义之前，服务器实现已经可用。相比之下，通用组件变更，即使尚未被大部分API实现者考虑到，也会广泛生效。
添加新消息或枚举是向后兼容的，因为不会影响到从同一通用组件包中导入消息或枚举的现有API。
对于全局通用组件，必须咨询API设计团队；对于组织特定通用组件，建议咨询API设计团队。“通用”和“组织特定”之间的界限模糊的；某些通用 概念 可能通过组件表现出组织特定场景。
修订记录
- 2023-06-27 重新组织AIP 215和213，让文字更清楚。正式引入组织特定通用proto概念。
- 2018-08-17 初稿。