版本控制

优质

小牛编辑

134浏览

2023-12-01

本章提供了网络 API 的版本控制指南。由于一个 API 服务可能提供多个 API 接口)，因此 API 版本控制策略适用于API 接口级别，而不适用于 API 服务)级别。为了方便起见，术语 API 指的是以下各节中的 API 接口。

网络API应该使用语义化的版本。比如给定版本号 MAJOR.MINOR.PATCH：

根据 API 版本，指定主要版本号（major version number）时可使用不同的规则：

对于 API 第一版（v1），其主要版本号应该编码进 proto 包名称中，例如 google.pubsub.v1。如果包中不含有将来会变化的类型和接口，例如 google.protobuf 和 google.longrunning，则可以从 proto 包中省略主版本号。
对于v1之外的所有版本的 API，主版本号必须编码进原包名中。例如，google.pubsub.v2。

对于 GA 之前的版本，例如 alpha 和 beta，建议在版本号后面附加一个后缀，应该包括预发布版本名称（例如alpha，beta）和预发布版本号。

版本升级示例：

版本	描述
v1alpha	alpha 版本
v1beta1	beta 版本。因为破坏兼容性可以接受，所以不需要更新版本号
v1beta1	可信测试版
v1beta2	可信测试版本迭代
v1test	带有假数据的可信测试版
v1	正式发布版
v1.1beta1	v1小改版的beta版
v1.1	v1小改版
v2beta1	新大版本的beta版
v2	新大版本，正式发布版

minor 和 patch 版本号应该反映在 API 配置和文档中，它们不允许被编码在原始程序包名称中。

注意：One Platform目前不支持 minor 和 patch 版本。 API 所有者需要通过 API 文档和发行说明记录它们。

API 的新 major 版本不能依赖于以前同样API的主要版本。 API 在了解相关的依赖性和稳定性风险的情况下可以依赖其他 API。 API 必须只依赖于其他API的最新稳定版本。

在一段时间内，同一 API 的不同版本必须能够在客户端应用程序中同时工作。这是为了帮助客户端从旧版本平滑过渡到更新版本的 API。

旧的 API 版本应该在其弃用期结束后删除。

由许多 API 共享的公用而稳定的数据类型，例如日期和时间，应该在单独的 proto 包中定义。如果需要进行中断更改，则必须引入新类型名称或具有新的主要版本的包名称。

向后兼容

确定向后兼容的修改是困难的。

以下列表是一份快速参考，如果您有任何疑问，请参阅兼容性部分以了解更多详细信息。