AIP-185 API版本管理

本主题描述了Google API使用的版本管理策略。通常这些策略适用于所有由Google管理的服务。

指南

所有Google API接口 必须 提供 主版本号 ，放置在protobuf包的末尾，并作为REST API的URI路径的第一部分。如果API需要进行不兼容的变更，请参考AIP-180和AIP-181中相关界面稳定级别对应的必要步骤。

注意 术语“主版本号”的用法来自于语义版本管理。然而与传统语义版本管理不同，Google API 不得 发布次要或补丁版本号。例如Google API使用 v1 ，而非 v1.0 、 v1.1 或 v1.4.2 。从用户的角度来看，次要版本更新是原地进行的，无需迁移即可获得新功能。

API新的主要版本 不得 依赖于同一API先前的主要版本。API界面 不得 依赖于其他API，AIP-213和AIP-215中提及的场景除外。

必须 允许客户端程序在合理的过渡期内同时使用不同版本的API。过渡期让客户端能顺利迁移到新版本。旧版本在关闭之前 必须 经过合理的、充分沟通确认的废弃周期。

对于具有alpha或beta稳定级别的版本，API 必须 按照下列策略之一，在protobuf包和URI路径的主要版本号后添加稳定级别：

• 基于渠道的版本管理（推荐）
• 基于发布的版本管理
• 基于可见性的版本管理

基于渠道的版本管理

稳定级别渠道 是在特定稳定级别下，接收原地更新的长期发布。每个主要版本在一个稳定级别下最多有一个渠道。在此策略下，最多有三个可用渠道：alpha、beta和稳定。

alpha和beta渠道 必须 在其版本后添加稳定级别，稳定渠道 不得 添加稳定级别。例如稳定渠道可以接收 v1 版本，但不能接收 v1beta 或 v1alpha 。同样的，beta 和 alpha 渠道的可以接受 v1beta 或 v1alpha 版本，但不能接收 v1 。每个渠道都在接收新功能时原地更新。

beta 渠道的功能 必须 是 稳定 渠道功能的超集，alpha 必须 是 beta 的超集。

废弃API功能

API 元素（域、消息、远程过程调用） 可以 在任何渠道中标记为废弃，表明不应再使用它们：

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

  // ...
}

废弃的API功能 不得 从 alpha 升级到 beta，或从 beta 升级到 稳定。换句话说，任何渠道中均 不得 出现“预计将废弃”功能。

beta 渠道功能，在标记为“废弃”并经过足够长的时间后， 可以 移除。我们建议废弃周期为 180 天。对于只存在于 alpha 渠道中的功能，废弃标记是可选的， 可以 在没有通知的情况下移除。如果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元素。按照惯例，可见性标签应始终使用大写字母。所有API元素都隐含使用 PUBLIC 标签，除非像前文示例中那样显式设置可见性标签。

每个可见性标签都是一个许可清单。API生产者需要向API消费者授予可见性标签，让消费者使用与标签相关联的API功能。换句话说，API可见性标签就像一个带有访问控制清单的API版本。

多个可见性标签 可以 通过逗号分隔字符串（例如 "PREVIEW,TRUSTED_TESTER" ）应用于同一元素。如果存在多个可见性标签，客户端只需使用其中 一个 （逻辑 OR ）。

默认情况下，授予API消费者的可见性标签用于验证传入请求。不过客户端也可以发送带有显式可见性标签的请求，如下所示：

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

单个 API 请求最多只能设定一个可见性标签。

API 生产者可以使用 API 可见性进行 API 版本管理，如 INTERNAL 和 PREVIEW 。新API功能从 INTERNAL 标签开始，然后移动到 PREVIEW 标签。当功能稳定、可广泛应用时，所有API可见性标签将从API定义中移除。

通常API可见性比API版本管理更容易实现增量更改，但它依赖于复杂的API基础设施支持。Google Cloud API通常使用API可见性支持预览功能。