AIP-213 通用组件

· [tommwq@126.com]

根据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的全局通用组件如下所示：

请注意，某些通用组件可能具有内部域。API通常应当仅依赖已开源的域。

Google API也可以导入google.iam.v1.*，它提供了在Google中使用的IAM消息。

注意许多API从其他包导入组件在内部使用（例如应用可见性标签或向内部基础设施提供指令）。只要公开组件不包含这些引用，也是可以的。

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 ）。

google.type 包为 API 中的常见概念提供了一套“标准库”类型。尽管类型会不定期新增且最终权威列表始终以代码为准，但以下几种类型值得特别关注：

google.type 包提供了API中的常见概念类型的“标准库”。类型会不定期增加，定义列表以代码为准。其中有几个类型值得注意：

有时可能需要向这些包或公用proto添加proto。请在GitHub上的AIP创建问题，请注意上述指南。

现有以下组织特定通用组件包，均符合上述指南：

现有以下通用组件包不符合上述指南，但不应构成后续类似包的先例。

通用组件实际上是没有版本控制：API在定义和实现上彼此独立发展。注入添加新域的更改在特定API中是向后兼容和可预测的，API团队可以保证在发布API定义之前，服务器实现已经可用。相比之下，通用组件变更，即使尚未被大部分API实现者考虑到，也会广泛生效。

添加新消息或枚举是向后兼容的，因为不会影响到从同一通用组件包中导入消息或枚举的现有API。

对于全局通用组件，必须咨询API设计团队；对于组织特定通用组件，建议咨询API设计团队。“通用”和“组织特定”之间的界限模糊的；某些通用概念可能通过组件表现出组织特定场景。