处理 API 版本控制

本页介绍如何对您的 API 进行版本控制以及如何部署到多个版本。

关于管理 API 版本的建议

在管理 API 版本时,请考虑以下建议:

  • 如果要引入增量式非重大更改,请保持 API 版本不变,并在现有 API 上进行部署。
  • 如果要对 API 引入重大更改,请递增 API 版本。
  • 如果要获得额外保护,也请递增 App Engine 应用版本,然后将新 API 版本部署到新的 App Engine 应用版本。这样,您就可以利用 App Engine 内置的灵活性在各 App Engine 版本之间快速切换,并在遇到意外问题时通过旧工作版本提供服务。

下表展示如何将后端 API 版本级联到不同的 App Engine 应用版本:

应用版本 后端 API 版本
1
  • v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

如上表中所示,对 API v1 引入了增量式非重大更新,并且每次更新都会覆盖之前的版本。引入重大更改时,API 版本递增至 v2,并部署到新的 App Engine 应用版本。这样,您便可以在需要时切换回以前的应用版本。

在上表中,请注意应用版本 2 支持您 API 的最新 v1 版本和新的 v2 版本。如果您没有从项目中删除现有的 v1 代码,则部署项目时,API 的 v2vl (n) 都将部署到应用的版本 2。

部署到多个应用版本

部署后端 API 时,您必须将其部署到您为 API 创建的 Google Cloud 项目的 ID,同时还必须指定要部署到的 App Engine 版本。您可以在 /WEB-INF/appengine-web.xml 文件的 <version> 元素中指定 App Engine 应用版本。App Engine 应用版本与后端 API 版本号不同,后者是在 @Api 注释的 version 属性中指定的。

apiversions

如上图所示,您可以将多个 API 版本部署到同一个 App Engine 版本,并且您可以为一个应用提供多个 App Engine 版本。

访问部署到服务版本的 API 版本

将 API 部署到的第一个 App Engine 版本即为服务版本。此版本的运行网址为 http://YOUR_PROJECT_ID.appspot.com,其中 YOUR_PROJECT_ID 代表您的 Google Cloud 项目 ID。您可以通过该网址访问部署到该 App Engine 应用版本的所有 API 版本。

除非您在 Google Cloud 控制台中明确更改了服务版本,否则此版本保持不变。

访问部署到非服务应用版本的 API 版本

如果您需要访问的 API 版本未部署到当前提供服务的 App Engine 版本,请使用特定于版本的网址,如下所示:

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

请将 VERSION 替换为您的 App Engine 版本,并将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如,假设您的 App Engine 服务版本为 1,但您想要访问部署到版本 2 的 API 版本,可以使用以下网址:https://2-dot-YOUR_PROJECT_ID.appspot.com

如需了解详情,请参阅 App Engine 文档

访问部署到非使用中服务(之前称作模块)的 API 版本

如果您需要访问的 API 版本未部署到默认 App Engine 服务,则您可以使用采用 dot 语法的特定于服务的网址,如下所示:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

如需了解详情,请参阅 App Engine 文档