本页面介绍 Cloud Endpoints API 版本控制功能，并提供有关 Endpoints API 版本控制和预演的最佳做法。本页面提供的信息适用于采用 OpenAPI 规范的 API。 如果 API 使用适用于 App Engine 标准环境的 Cloud Endpoints Frameworks，请参阅处理 API 版本控制：Java 或处理 API 版本控制：Python。
建议您遵循 Google 用于 API 版本控制和服务预演的基本原则：
在部署初始版本之前，请在您的 OpenAPI 配置文件中添加以下内容：
- 在
info.version字段中设置版本号。 建议使用包含主要版本号和次要版本号的版本字符串，例如1.0。 - 设置
basePath字段以包含主要版本号。建议使用的基本路径格式为字母v后跟主要版本号，例如/v1。
- 在
当您需要进行向后兼容的更改（例如添加新方法）时，请递增
info.version字段中的次要版本号（1.2、1.3 等）并重新部署。如需了解详情，请参阅对 API 进行版本控制。如果您要对现有方法进行的更改会破坏客户端代码，请复制 OpenAPI 配置文件，并进行以下更改：
- 递增
info.version字段中的主要版本号（2.0、3.0 等）。 - 递增
basePath字段中的主要版本号（/v2、/v3 等）。
部署两个 OpenAPI 配置文件版本，然后重新部署后端，此后端现在包含了该方法的两个版本。如需了解详情，请参阅对 API 进行版本控制。
- 递增
在单个后端实现所有主要 API 版本。此建议可以：
- 简化路由，因为发送到特定版本的请求是基于路径的，如前面的例子所示。
- 简化配置和部署。对 API 的所有主要版本都使用相同的 Google Cloud 项目和后端，并同时部署所有的 API 版本。
- 避免运行多余的后端，从而降低费用。
在将 API 部署到生产 Google Cloud 项目之前，请先在单独的 Google Cloud 项目中对 API 进行预演。如需了解详情，请参阅预演服务。
在 Endpoints 中使用的主要版本号和次要版本号对应于语义版本控制中的相应定义。在后端代码中部署问题修复时，虽然 Endpoints 不要求您在 OpenAPI 配置文件中递增补丁程序版本号并部署该配置，但您可以根据需要这样做。
Cloud Endpoints API 版本控制功能
只要 API 的多个主要版本没有重叠路径，Extensible Service Proxy (ESP) 就能够在单个 Google Cloud 项目和后端中同时管理它们。例如：
http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo
这样，您的客户可以选择他们想要使用的版本，以及控制何时迁移到新版本。ESP 会使用版本号标记每个请求，然后再将请求路由到后端中的相应方法。由于每个请求都标有版本号：
Endpoints > 服务页面中的图表和日志可显示来自各个主要 API 版本的请求以及所有版本的汇总数据。您可以过滤您的视图以显示特定版本。这样，您能够清楚地了解每个版本收到的流量。日志甚至可以告诉您哪些客户端正在使用哪个版本。
使用次要版本号更新重新部署 API 时，系统将使用图表和日志中的新版本号标记后续活动，这就为您提供了带标签的部署历史记录。
移除某 API 的某个版本时，图表和日志中仍会继续显示该 API 处于活跃状态的时间范围内的数据。
API 生命周期示例
本部分介绍服务的典型发展过程。
版本 1
您最初部署了 My Awesome Echo API 服务的版本 1。此 API 通过 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo 提供。在 Endpoints > 服务中显示的图形和日志中，您会看到所有流量均位于 1.0 版本。
版本 1.1
您的客户提出新的功能需求，因此您需要添加新的方法。在 OpenAPI 配置文件中，添加新方法并将 info.version 字段递增为 1.1。由于这项更改不会破坏客户端代码，因此您可以递增次要版本号。您在预演环境中部署和测试更改，确保更改能正常运行。
接下来，您将 OpenAPI 配置和 API 后端部署到生产环境。此 API 仍然通过 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo 提供，但现在调用者可以向新方法发出请求。由于您没有更改旧方法的接口，因此您的客户无需更改和重新部署其客户端；客户端可以像以前一样向旧方法发送请求。
在 Endpoints > 服务中，处理的流量现在位于 1.1 版本。如果您选择显示较早的时间范围，则系统就会在图表和日志中显示先前版本，从而提供带标签的部署历史记录。
版本 2.0
随着时间的推移，您意识到需要对现有方法进行不向后兼容的更改。由于不破坏客户的客户端代码很重要，因此您决定维护两个 API 版本。您将旧方法保留原样，并实现该方法的新版本。您为版本 2.0 另外创建了一个 OpenAPI 配置文件，并将新版本配置为通过 my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo 提供。您原来的 OpenAPI 配置文件仍指向该方法的旧版本，而新的 OpenAPI 配置文件则指向该方法的新版本。
您同时部署版本 1 和版本 2 的 OpenAPI 配置文件，并重新部署后端，后端现在包含该方法的两个版本。 （如需了解详情，请参阅对 API 进行版本控制。）
部署后，Endpoints > 服务会显示您的 API 有两个版本，并且您可以看到每个版本获得的流量。v1 客户端可以继续调用 /v1，但也可以调用 /v2 来使用该方法的新版本。如何处理后端代码中的版本控制取决于您使用的 API 框架。如需了解 servlet 的用法示例，请参阅具有多个版本的 Endpoints 和 Java 示例。
停用版本 1
一段时间后，当您的客户端迁移并且您发现流向版本 1 的所有流量都已停止时，您可以停止该服务。如需移除 API 的版本 1，请仅部署版本 2 的 OpenAPI 配置文件并重新部署后端。您现在可以安全地从后端移除版本 1 的实现代码。 Endpoints > 服务将保留版本 1.x 的历史数据。
预演服务
我们建议的最佳做法是，对 Endpoints 服务的更新进行预演，以便在向客户提供服务之前先对其进行测试。此外，也建议您单独创建一个 Google Cloud 项目来预演您的服务，以便将其从生产环境中隔离出来。例如，Google 配额通常由项目内的资源共享。因此，如果将预演服务放在与生产级服务相同的项目，那么一旦发生问题（例如错误的 for 循环），就可能会导致生产级服务中断。
建议您在设计 Google Cloud 项目名称时应该确保此名称能够明确表明项目用于预演用途。常见的命名策略是使用与生产级 Google Cloud 项目相同的名称，但要在末尾加上 -staging。您也不妨在生产级项目名称中加上 -prod，以明确表示该项目支持的是生产级服务。
Google Cloud 上的服务名称不得重复。因为您在 OpenAPI 配置文件中指定服务的名称，所以您需要为预演项目和生产级项目分别维护各自的 API 配置文件，或使用一组 API 配置文件，并设计适当流程，以便更改服务名称来与要部署到的项目名称相匹配。