编号	215
原文链接	AIP-215: API-specific protos
状态	批准
创建日期	2018-10-01
更新日期	2018-10-01

API通常使用API特定proto定义，偶尔依赖通用组件。保持API相互隔离可以避免版本问题和客户端库打包问题。

指南

• 所有特定于某个API的protos 必须 位于带有主版本号的包中（例如 google.library.v1 ）。
• 对其他API中资源的引用 必须 通过资源名字（AIP-122）表达，而非使用资源消息。
• 如果API的两个版本实际上使用相同的（API特定）proto，这个proto 必须 每个版本中独立定义。（换句话说，API 不得 创建自己的“API特定通用组件”包。）
• 组织特定通用组件 可以 放在一个通用包中，如AIP-213所述，但 不得 被该组织外的任何API使用。
• 全局通用组件（一如AIP-213所述） 可以 被任何API自由使用。

理由

如果一个API依赖于另一个API定义的protos，这会引发客户预期行为和客户端库依赖管理的不确定性。假设 google.cloud.library.v1 依赖于 google.cloud.movies.v2 中的protos（而非抽象资源）。对 google.cloud.movies.v2 的任何更改都可能产生问题。

例如：

• 如果向 google.cloud.movies.v2 中的消息添加了一个域，使用 google.cloud.library.v1 的客户是否应该能够看到它？如果是，应该在域添加后的多久之后看到？其他API更改呢？
• 如果整个主版本 google.cloud.movies.v2 废弃了（通常在v3发布后），这是否意味着 google.cloud.library.v1 必须更改为使用 google.cloud.movies.v3 ？如果是，需要为库API发布一个新的主版本吗？
• 客户端库版本管理应该如何反映所依赖API的变更？

保持API相互隔离，并按照高度的纪律性维护一组有限的通用组件，可以减少许多依赖问题。

如果在多个版本之间共享API特定通用组件，会增加生成和打包客户端库的复杂性，在版本管理上也缺乏灵活性。

如果多个主版本初始包含同一个proto的副本，每个proto副本都可以随版本演进，因为它们相互独立。

修订记录

• 2023-06-27 重构了AIP 215和213，提升清晰度。
• 2023-05-11 将“PA”改为“组织”。
• 2018-10-01 初稿。