版本化

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

网络API应该使用语义化版本控制。对于某一个版本号MAJOR.MINOR.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版本号组成。

版本演进的例子：

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版本。

向后兼容性

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

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

Last updated 5 years ago