版本控制
提供了网络 API 的版本控制指南。由于一个 API 服务可能提供多个 [API 接口](17-术语表.md#API接口(API Interface))，因此 API 版本控制策略适用于API 接口级别，而不适用于 [API 服务](17-术语表.md#API服务(API Service))级别。 为了方便起见，术语 API 指的是以下各节中的 API 接口。网络API应该使用语义化的版本。比如给定版本号 MAJOR.MINOR.PATCH：
- 当做出不兼容修改的时候，修改
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 包中定义。如果需要进行中断更改，则必须引入新类型名称或具有新的主要版本的包名称。
向后兼容
确定向后兼容的修改是困难的。
以下列表是一份快速参考，如果您有任何疑问，请参阅兼容性部分以了解更多详细信息。
向后兼容的修改
- 将 API 接口添加到 API 服务定义
- 向 API 接口添加方法
- 向方法添加 HTTP 绑定
- 向请求消息中添加字段
- 向响应消息中添加字段
- 向枚举添加值
- 添加仅输出的资源字段
向后不兼容的修改
- 删除或重命名服务，字段，方法或枚举值
- 更改 HTTP 绑定
- 更改字段的类型
- 更改资源命名格式
- 更改现有请求的可见行为
- 更改 HTTP 定义中的 URL 格式
- 向资源消息添加读/写字段