版本控制

本主题介绍 Google API 使用的版本控制政策。通常,这些政策适用于所有 Google 托管式服务。

有时,您需要对 API 进行不向后兼容(或“间断”)的更改。这些类型的更改可能导致依赖于原始功能的代码出现问题或损坏。

Google API 使用版本控制方案来防止重大更改。此外,Google API 仅在某些稳定性级别下提供某些功能,例如 Alpha 版和 Beta 版组件。

指南

所有 Google API 接口都必须提供一个主要版本号,该版本号在 protobuf 软件包的末尾编码,并作为 REST API 的 URI 路径的第一部分。如果 API 引入了重大更改(例如删除或重命名字段),则该 API 必须增加其 API 版本号,以确保现有用户代码不会突然中断。

新的 API 主要版本不得依赖于同一 API 的先前主要版本。某一个 API 可以依赖于其他 API,前提是了解这些 API 的依赖项和稳定性风险。在这种情况下,稳定的 API 版本必须只依赖于其他 API 的最新稳定版本。

在一段时间内,同一 API 的不同版本必须能够在单个客户端应用中同时工作。在该时间段内,客户端可以平稳过渡到新版本。旧版必须必须通过合理且经过良好沟通的弃用期,然后才能关闭。

对于具有 Alpha 版或 Beta 版稳定性的版本,API 必须使用以下两种策略之一在 Protobuf 软件包和 URI 路径的主要版本号后面附加稳定性级别:

  • 基于发布版本的版本控制(推荐)
  • 基于版本的版本控制

基于发布版本的版本控制

稳定版是在给定稳定性级别接收就地更新的长效版本。主版本的每个稳定性级别不超过一个发布版本。在此策略下,您最多可以使用三种发布版本:Alpha 版、Beta 版和稳定版。

Alpha 版和 Beta 版必须附加其稳定性级别,但稳定版不得附加稳定性级别。例如,v1 是稳定版的可接受版本,但 v1betav1alpha 不是。同样,v1betav1alpha 是各自的 Alpha 版和 Beta 版的可接受版本,但 v1 不能作为其中任何一个。每一个发布版本都会获得新的功能和“就地”更新。

Beta 版的功能必须是稳定版功能的超集,而 Alpha 版的功能必须是 Beta 版功能的超集。

弃用 API 功能

API 元素(字段、消息、RPC)可能在任何发布版本中被标记为“已弃用”,表明其已不再使用:

// A representation of a scroll.
// Books are now preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

弃用的 API 功能不得从 Alpha 版升级到 Beta 版,而不能从 Beta 版升级到稳定版。换句话说,就是功能不得在任何发布版本中“预先弃用”。

Beta 版的功能可以在其弃用足够时间(建议 180)后移除。对于仅存在于 Alpha 版中的功能,您可以选择是否弃用,该功能可能会被移除,恕不另行通知。如果在移除该功能之前它已在 API 的 Alpha 版中弃用,则 API 应该应用相同的注释,并且可以使用其希望使用的任何时间范围。

基于版本的版本控制

单独版本是 Alpha 版或 Beta 版,预计在其功能整合到稳定版之前,会在有限的时间段内提供,在此之后,我们将关停单独版本。使用基于版本的版本控制策略时,API 在每个稳定性级别上可以有任意数量的单独版本。

Alpha 和 Beta 版必须附加其稳定性级别,后跟递增的版本号。例如 v1beta1v1alpha5。API 应该在其文档(如备注)中记录这些版本的时间顺序。

每个 Alpha 版或 Beta 版可以使用向后兼容的更改进行更新。对于 Beta 版,向后兼容的更新应该通过增加版本号并发布带有更改的新版本来创建。例如,如果当前版本为 v1beta1,则接下来将发布 v1beta2

其功能到达稳定版后,应该关闭 Alpha 和 Beta 版本。Alpha 版本随时都可以关闭,而 Beta 版本应该让用户有一个合理的过渡期;建议为 180 天。