跳到主要内容
版本：3.9.x

API 版本控制

在业务逻辑发生变更后维持 API 功能，需要更新 API 网关上的配置。API7 网关通过在服务（Service）级别提供强大的版本控制功能，简化了这一过程。你可以将特定的服务版本及其相应配置发布到不同的网关组中，从而确保部署的一致性并实现更平滑的回滚。

在 API7 网关中，并未强制要求进行严格的版本控制。是否实施哪怕最基础的版本控制系统，取决于你的组织需求以及希望对 API 网关配置达到的控制水平。

版本控制范围​

唯一的服务版本号代表着一致的业务逻辑。

路由/Stream 路由​

在 API7 网关中，路由（Route）或 Stream 路由的更改（除了插件和超时配置）均与服务版本绑定。 在已发布的服务版本中修改路由或 Stream 路由，可能会对正在使用这些 API 的开发者造成影响。这是因为他们现有的代码可能是依赖于先前路由配置的特定行为编写的。

上游​

API7 网关依赖上游（Upstream）配置来管理其与后端应用程序（例如，服务器和数据库）之间的连接。 这些配置决定了网关如何与后端进行交互，且它们通常会因部署环境的不同而有所差异。

例如，在开发环境中，API 网关可能会配置为连接运行在开发者机器上的应用程序（如 devserver）。 而在生产环境中，它将连接部署在数据中心的实际后端服务器。

但请务必注意，上游配置本身独立于你的 API 核心逻辑。上游配置关注于通信的“方式（how）”，而你的 API 代码则关注于“内容（what）”——即它提供的具体功能。

即使在相同的 API 版本下，不同的网关组也可以通过上游配置指向不同的后端服务器。使用这些 API 的开发者不会受到影响。无论底层的后端配置如何，其代码对 API 的调用都会保持完全一致的运行结果。

总体而言，API7 企业版中的上游配置作为“运行时配置（runtime configurations）”提供了极大的灵活性。它们独立于版本控制，允许你随时进行修改而无需发布新的版本。

Host、路径前缀​

主机（Host）和路径前缀（Path Prefix）是 API7 网关中的配置元素，用于管理客户端如何访问你的 API。它们独立于你的 API 所实现的核心逻辑，主要关注 API 调用的“位置（where）”和“方式（how）”。

主机和路径前缀可以根据你的部署环境（开发、预发布、生产）而变化，以便为各个阶段提供适当的访问点。更改主机或路径前缀通常要求开发者更新代码以反映新的访问详情。然而，与修改核心 API 逻辑相比，这种更新往往只需要替换代码中的主机地址或路径前缀，而不是进行全面的重写。这在管理环境特定配置时，将对开发者造成的干扰降到了最低。

例如：

总体而言，API7 网关中的主机和路径前缀作为“运行时配置（runtime configurations）”提供了灵活性。它们独立于版本控制，允许你随时修改而无需发布新版本。

插件​

插件（Plugin）配置被视为“运行时配置”，并且可以在不同的网关组之间有所差异。一个常见的场景是，基于安全考虑，为每个网关组应用不同的限流（Rate Limiting）规则，即便是同一个 API 也是如此。

此外，插件配置与运行时性能紧密相关。这意味着可能需要在 API 运行期间对合适的插件参数进行测试和修改，要在发布之前预先确定所有插件设置是具有挑战性的。因此，插件只能直接添加到网关组，不能包含在服务模板内，也不与特定的服务版本关联。

关键特性​

  1. 服务变更追踪：维护清晰的历史记录

服务版本会记录对你的服务所做的每一项修改，包括做了哪些具体修改、由谁进行的修改以及修改的确切时间等细节。这种详细的历史记录提供了许多优势。它能让你通过将问题追溯到具体修改来实现更快的调试。

  1. 服务回滚：应对意外问题的安全网

在新的配置部署引发问题时，服务回滚将作为一个安全网。如果出现了意外后果或故障，你可以迅速回滚到已知良好的版本。这种回滚能力可以最大限度地减少停机时间，确保为你的用户提供服务连续性，避免业务中断。

  1. 网关组同步：跨部署保持一致的配置

对于涉及多个网关组的复杂部署，在所有组之间保持相同配置是至关重要的。服务版本管理通过同步功能简化了这一过程。这可以确保所有网关组都拥有完全相同的 API 逻辑相关配置，保证你的 API 调用的行为一致性以及开发者的良好体验。

使用合理的版本号​

  • 大版本增加（v1、v2）仅在需要进行破坏性更改（breaking changes）时使用。
  • 小版本增加（v1.1）优先用于向后兼容的更新。
  • 修复错误（Bug-fixing）的版本增加（v1.1.1）应该对 API 消费者无害。
  • 不要重复使用已废弃的版本号。

典型的版本控制工作流​

  1. 为 test（测试）和 production（生产）环境添加两个网关组。
  2. 将服务发布到 Test Group（测试组），服务版本设为 1.0.0。
  3. 在 test 环境中验证 API。
  4. 更新服务模板中的 API 配置。
  5. 将错误修复再次发布到 Test Group，版本为 1.0.1。
  6. 将服务同步到 Production Group（生产组），服务版本为 1.0.1。
  7. 对于新的 sprint，编辑服务模板以添加更多路由。
  8. 将服务发布到 Test Group，服务版本设为 1.1.0。
  9. 在 test 环境中验证 API，期间发生了紧急情况。
  10. 将服务版本回滚到 1.0.0 进行恢复。

其他资源​