API 版本控制
在逻辑变更后保持 API 功能需要更新 API 网关上的配置。API7 网关通过强大的服务级版本控制简化了这一过程。你可以将特定的服务版本及其相应的配置发布到不同的网关组,从而确保一致的部署和更平滑的回滚。
API7 网关并不强制要求强版本控制。是否实施甚至一个基本的版本控制系统取决于你的组织的具体需求和对 API 网关配置所需的控制级别。
版本控制范围
唯一的服务版本号表示一致的业务逻辑。
路由/四层路由 - 包含
API7 网关中的路由/四层路由更改与服务版本相关联。修改已发布服务版本中的路由/四层路由可能会对使用这些 API 的开发者造成干扰。这是因为他们现有的代码可能依赖于先前路由配置的特定行为。
上游 - 不包含
API7 网关依赖上游配置来管理与其后端应用程序(例如,服务器和数据库)的连接。这些配置决定了网关如何与后端交互,并且它们通常因部署环境而异。
例如,在开发环境中,API 网关可以配置为连接到开发者机器上运行的应用程序(例如,devserver)。而在生产环境中,它将连接到部署在数据中心中的实际后端服务器。
但是,需要注意的是,上游配置本身独立于 API 实现的核心逻辑。它们专注于通信的“方式”,而你的 API 代码专注于“内容”——它提供的特定功能。
即使使用相同的 API 版本,不同的网关组也可以通过上游配置指向不同的后端服务器。使用这些 API 的开发者不受影响。无论底层后端配置如何,他们的代码对 API 的调用都将以相同的方式运行。
通常,API7 网关中的上游配置提供了“运行时配置”的灵活性。它们独立于版本控制,允许你随时修改它们而无需发布新版本。
主机,路径前缀 - 不包含
主机和路径前缀是 API7 网关中的配置元素,用于管理客户端如何访问你的 API。它们独立于 API 实现的核心逻辑,专注于 API 调用的“位置”和“方式”。
主机和路径前缀可以根据你的部署环境(开发、暂存、生产)而变化,为每个阶段提供适当的接入点。更改主机或路径前缀通常需要开发人员更新他们的代码以反映新的访问详细信息。然而,与修改核心 API 逻辑相比,这种更新通常涉及替换代码中的主机地址或路径前缀,而不是完全重写。这最大限度地减少了开发人员在管理特定于环境的配置时受到的干扰。
例如:
test
环境中的 API 网址为 https://api7-test.ai/v1/pet,而端点地址为 127.0.0.1:80。production
环境中的 API 网址为 https://api7.ai/petstore/pet,而端点地址为 192.168.0.1:80。
通常,API7 网关中的主机和路径前缀提供了“运行时配置”的灵活性。它们独立于版本控制,允许你随时修改它们而无需发布新版本。
关键特性
服务变更跟踪:保持清晰的历史记录
服务版本记录对你的服务所做的每一个修改,包括所做的具体变更、变更人以及变更的确切时间等细节。这种详细的历史记录提供了几个优势。它允许通过使你能够将问题追溯到特定的更改来更快地调试。
服务回滚:意外问题的安全网
这可以作为安全网,以防新的配置部署引入问题。如果出现意外后果或故障,你可以快速回滚到已知的良好版本。这种回滚能力最大限度地减少了停机时间,并确保了用户的服务连续性,防止了中断。
网关组同步:跨部署的一致配置
对于涉及多个网关组的复杂部署,在所有组中保持相同的配置至关重要。服务版本管理通过同步功能简化了这一过程。这确保了所有网关组具有完全相同的 API 逻辑相关配置,从而保证了你的 API 调用的行为一致性,而不受开发人员体验的影响。
使用合理的版本号
- 主版本增量(v1、v2)仅在需要重大更改时才使用。
- 小版本增量(v1.1)优先用于向后兼容性。
- 错误修复版本增量(v1.1.1)对 API 使用者应该是无害的。
- 不要重复使用已弃用的版本号。
典型的版本控制工作流程
- 为
测试
和生产
环境添加两个网关组。 - 将服务发布到
测试网关组
,服务版本为1.0.0
。 - 在测试环境中验证 API。
- 更新服务模板中的 API 配置。
- 使用版本
1.0.1
再次将错误修复发布到测试网关组
。 - 使用服务版本
1.0.1
将服务同步到生产网关组
。 - 对于新的迭代,编辑服务模板以添加更多路由。
- 使用服务版本
1.1.0
将服务发布到测试网关组
。 - 在测试环境中验证 API 并发生紧急情况。
- 将服务版本回滚到
1.0.0
进行恢复。
相关阅读
- 核心概念
- 快速入门