> For the complete documentation index, see [llms.txt](https://google-cloud.gitbook.io/api-design-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://google-cloud.gitbook.io/api-design-guide/versioning.md).

# 版本化

一个API服务可能提供多个API接口，API版本策略是应用在API 接口层面上而不是API服务层面上的。为了方便起见，下面所有的API均指API接口。

网络API应该使用[语义化版本控制](http://semver.org/)。对于某一个版本号`MAJOR.MINOR.PATCH`：

* 当你有不兼容的更改时，增加 `MAJOR`版本号。
* 当你以向后兼容的方式添加新的功能时，增加`MINOR`版本号。
* 当你修复了可以向后兼容的bug时，增加`PATCH`版本号。

当API所处的版本不一样时，增加`MAJOR`版本的规则也会不一样：

* 对于API的第一个版本（v1），其`MAJOR`版本号应该加在proto包名称的末尾，例如`google.pubsub.v1`。有一种极为罕见的情况`MAJOR`版本号就可以被省略，那就是API包含显而易见的稳定类型和结构，并且预计它不会有不兼容的改动，例如`google.protobuf`和`google.longrunning`。
* 对于所有不是v1的版本，`MAJOR`版本号必须加在proto包的末尾，例如，`google.pubsub.v2`。

对于pre-GA版本（如alpha和beta），我们推荐在其版本号后面加上一个相应的后缀。这个后缀应该由pre-release版本名称（例如 alpha，beta）和一个可选的pre-release版本号组成。

版本演进的例子：

| 版本        | Proto包    | 描述                 |
| --------- | --------- | ------------------ |
| v1alpha   | v1alpha1  | v1 alpha版本.        |
| v1beta1   | v1beta1   | v1 beta1版本.        |
| v1beta2   | v1beta2   | v1 beta2版本.        |
| v1test    | v1test    | 用假数据进行测试的内部测试v1版本. |
| v1        | v1        | v1主版本，基本稳定.        |
| v1.1beta1 | v1p1beta1 | v1微小更改后的第一个beta版本. |
| v1.1      | v1        | v1.1版本的一个小升级.      |
| v2beta1   | v2beta1   | v2 beta 1版本.       |
| v2        | v2        | v2主版本, 基本稳定.       |

`MINOR`和`PATCH`版本号应该在API的配置和文档里面反映出来，但是他们一定不可以放在proto包名称里面。

注：Google API平台目前没有原生支持`MINOR` 和`PATCH`版本号。每一个 `MAJOR`版本只有一套文档和客户端的库。API的作者需要通过文档和发布日志手动记录`MINOR`和`PATCH`版本号。

一个API新的主版本一定不能依赖于先前主版本的相同API。在了解了依赖性和稳定性风险后，API可以依赖于其他的API，不过一个稳定的API版本一定只能依赖于其他API最新的稳定版本。

在某段时间内，相同API的不同版本必须能够同时在单个客户端中工作。这样才能帮助客户端从旧版API平滑迁移到新版API。

只有弃用期结束后，旧的API版本才能被移除。

在多个API中共享的通用稳定的数据类型，例如日期和时间等，应该定义在单独的proto包里面。如果有必要进行不兼容的改动，就必须引入带有新的类型名称或者新的包名称的`MAJOR`版本。

## 向后兼容性

有时候很难去判断一个改变是否是向后兼容的。

下面列出了一些供你快速检索的起点，如果你还有疑惑，可以点击查看[设计兼容页面](broken://pages/-LClT2NVn6BxtWfeq5B_)以获取更多的细节。

### 保持向后兼容的改动

* 添加API接口到API服务
* 添加方法到API接口
* 添加HTTP绑定到方法
* 添加字段到请求消息
* 添加字段到响应消息
* 添加值到某个枚举类型
* 添加output-only的资源字段

### 不能向后兼容的改动

* 删除/重命名服务、接口、字段名、方法或枚举值
* 修改HTTP绑定
* 修改字段类型
* 修改资源名的格式
* 修改已有请求的可见性
* 修改HTTP定义中的URL格式
* 在资源消息中添加读/写字段