谷歌API 设计指南

版本控制

Preview
1年前
  • 指南
  • 基于发布版本的版本控制
  • 弃用 API 功能
  • 基于版本的版本控制
  • 基于公开范围的版本控制

本主题介绍 Google API 使用的版本控制策略。通常，这些政策适用于所有 Google 托管式服务。 有时，您需要对 API 进行不向后兼容（或“间断”）的更改。这些类型的更改可能导致依赖于原始功能的代码出现问题或损坏。 Google API 使用版本控制方案来防止重大更改。此外，Google API 仅在某些稳定性级别下提供某些功能，例如 Alpha 版和 Beta 版组件。

指南

所有 Google API 接口都必须提供一个主要版本号，该版本号在 protobuf 软件包的末尾编码，并作为 REST API 的 URI 路径的第一部分。如果 API 引入了重大更改（例如删除或重命名字段），则该 API 必须增加其 API 版本号，以确保现有用户代码不会突然中断。 注意：上面使用的术语“主要版本”取自语义版本控制。但是，与传统的语义版本控制不同的是，Google API 不得公开次要或补丁版本号。例如，Google API 使用 v1，而不使用 v1.0、v1.1 或 v1.4.2。从用户的角度来看，主要版本可以更新，并且用户无需迁移即可获得新功能。 新的 API 主要版本不得依赖于同一 API 的先前主要版本。某一个 API 可以依赖于其他 API，前提是了解这些 API 的依赖项和稳定性风险。在这种情况下，稳定的 API 版本必须只依赖于其他 API 的最新稳定版本。 在一段时间内，同一 API 的不同版本必须能够在单个客户端应用中同时工作。在该时间段内，客户端可以平稳过渡到新版本。旧版必须必须通过合理且经过良好沟通的弃用期，然后才能关闭。 对于具有 Alpha 版或 Beta 版稳定性的版本，API 必须使用以下这些策略之一在 Protobuf 软件包和 URI 路径的主要版本号后面附加稳定性级别：

  • 基于发布版本的版本控制（推荐）
  • 基于版本的版本控制
  • 基于公开范围的版本控制

基于发布版本的版本控制

稳定版是在给定稳定性级别接收就地更新的长效版本。主版本的每个稳定性级别不超过一个发布版本。在此策略下，您最多可以使用三种发布版本：Alpha 版、Beta 版和稳定版。 Alpha 版和 Beta 版必须附加其稳定性级别，但稳定版不得附加稳定性级别。例如，v1 是稳定版的可接受版本，但 v1beta 或 v1alpha 不是。同样，v1beta 或 v1alpha 是各自的 Beta 版和 Alpha 版的可接受版本，但 v1 不能作为其中任何一个。每一个发布版本都会获得新的功能和“就地”更新。 Beta 版的功能必须是稳定版功能的超集，而 Alpha 版的功能必须是 Beta 版功能的超集。

弃用 API 功能

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

// Represents a scroll. Books are preferred over scrolls.message Scroll {  option deprecated = true;  // ...}

弃用的 API 功能不得从 Alpha 版升级到 Beta 版，而不能从 Beta 版升级到稳定版。换句话说，就是功能不得在任何发布版本中“预先弃用”。 Beta 版的功能可以在其弃用足够时间（建议 180）后移除。对于仅存在于 Alpha 版中的功能，您可以选择是否弃用，该功能可能会被移除，恕不另行通知。如果在移除该功能之前它已在 API 的 Alpha 版中弃用，则 API 应该应用相同的注释，并且可以使用其希望使用的任何时间范围。

基于版本的版本控制

单独版本是 Alpha 版或 Beta 版，预计在其功能整合到稳定版之前，会在有限的时间段内提供，在此之后，我们将关停单独版本。使用基于版本的版本控制策略时，API 在每个稳定性级别上可以有任意数量的单独版本。 注意：基于发布版本的策略和基于版本的策略均会就地更新稳定版。即使使用基于版本的策略，也只有一个稳定的发布版本，而不是单独的稳定版本。 Alpha 和 Beta 版必须附加其稳定性级别，后跟递增的版本号。例如 v1beta1 或 v1alpha5。API 应该在其文档（如备注）中记录这些版本的时间顺序。 每个 Alpha 版或 Beta 版可以使用向后兼容的更改进行更新。对于 Beta 版，向后兼容的更新应该通过增加版本号并发布带有更改的新版本来创建。例如，如果当前版本为 v1beta1，则接下来将发布 v1beta2。 其功能到达稳定版后，应该关闭 Alpha 和 Beta 版本。Alpha 版本随时都可以关闭，而 Beta 版本应该让用户有一个合理的过渡期；建议为 180 天。

基于公开范围的版本控制

API 公开范围是 Google API 基础架构提供的高级功能。它允许 API 提供方从一个内部 API 表面公开多个外部 API 视图，并且每个视图都与 API 公开范围标签相关联，例如：

import "google/api/visibility.proto";
message Resource {
  string name = 1;

  // Preview. Do not use this feature for production.
  string display_name = 2
    [(google.api.field_visibility).restriction = "PREVIEW"];}

公开范围标签是一个区分大小写的字符串，可用于标记任何 API 元素。按照惯例，公开范围标签应始终使用大写。隐式 PUBLIC 标签适用于所有 API 元素，除非应用上述示例可见性标签。 每个公开范围标签也是一个允许列表。API 提供方需要向 API 使用方授予公开范围标签，他们才能使用与标签关联的 API 功能。换句话说，API 公开范围标签类似于 ACL 的 API 版本。 可以使用英文逗号分隔的字符串（例如 "PREVIEW,TRUSTED_TESTER"）为元素应用多个可见性标签。如果使用多个可见性标签，则客户端只需要其中一个可见性标签（逻辑 OR）。 单个 API 请求只能使用一个公开范围标签。默认情况下，使用授予 API 使用方的公开范围标签。客户端可以发送带有显式公开范围标签的请求，如下所示：

GET /v1/projects/my-project/topics HTTP/1.1Host: pubsub.googleapis.comAuthorization: Bearer y29....
X-Goog-Visibilities: PREVIEW

API 提供方可以为 API 版本控制使用 API 公开范围，例如 INTERNAL 和 PREVIEW。一项新的 API 功能以 INTERNAL 标签开头，然后转到 PREVIEW 标签。当功能保持稳定并且正式发布时，所有 API 公开范围标签都将从 API 定义中被移除。 通常，与增量更改的 API 版本控制相比，API 公开范围更容易实现，但它依赖于复杂的 API 基础架构支持。Google Cloud API 通常将 API 公开范围用于预览功能。