网站建设策划书范文案例商城网站 备案
| 编号 | 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 初稿。