当前位置：首页 > article >正文

AIP-213 通用组件

article 2026/2/6 11:35:05

编号	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 初稿。

指南