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

AIP-215 API特定proto

news 来源：原创 2025/6/19 16:20:17

编号	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副本都可以随版本演进，因为它们相互独立。