版本控制

本章提供了网络 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 包中定义。如果需要进行中断更改，则必须引入新类型名称或具有新的主要版本的包名称。

向后兼容

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

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