Apache APISIX 多版本 API 管理实战指南

Apache APISIX 多版本 API 管理实战指南

apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/gh_mirrors/ap/apisix

什么是 API 版本管理？

在现代 API 开发中，API 版本管理是一项关键实践，它允许开发者在不中断现有客户端的情况下对 API 进行迭代更新。一个良好的版本管理策略能够清晰地传达变更内容，并让 API 使用者自主决定何时升级到最新版本。

常见的 API 版本控制方式

1. URI 路径版本控制

这是最常见的版本控制方式，通过在 URI 路径中加入版本前缀（如 "v1"、"v2"）来区分不同版本：

http://apisix.org/v1/hello
http://apisix.org/v2/hello

优点：直观明了，易于理解和实现。

2. 查询参数版本控制

将版本号作为查询参数附加在 URI 中：

http://apisix.org/hello?version=1
http://apisix.org/hello?version=2

适用场景：当不想改变 URI 结构时使用。

3. 自定义请求头版本控制

通过自定义 HTTP 头部来指定版本号，保持 URI 不变：

http://apisix.org/hello -H 'Version: 1'
http://apisix.org/hello -H 'Version: 2'

优势：URI 保持简洁，适合 RESTful 设计原则。

实战：使用 Apache APISIX 实现多版本 API

环境准备

1. 确保已安装 Docker 环境
2. 准备一个 Spring Boot 示例应用作为 API 后端

基础路由配置

首先创建一个基础路由，将请求转发到旧版 API：

curl http://apisix:9180/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PUT -d '
{
  "name": "旧版API路由",
  "methods": ["GET"],
  "uris": ["/hello", "/hello/", "/hello/*"],
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "oldapi:8081": 1
    }
  }
}'

测试访问：

curl http://apisix.org/hello
# 输出：Hello world

创建共享上游

为了提高配置复用性，我们可以创建独立的上游配置：

curl http://apisix:9180/apisix/admin/upstreams/1 -H 'X-API-KEY: xyz' -X PUT -d '
{
  "name": "旧版API上游",
  "type": "roundrobin",
  "nodes": {
    "oldapi:8081": 1
  }
}'

添加 API 新版本

1. 配置路径重写插件

由于新旧版本共享同一上游，我们需要重写请求路径：

curl http://apisix:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PUT -d '
{
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["/v1/(.*)", "/$1"]
    }
  }
}'

2. 创建版本化路由

curl http://apisix:9180/apisix/admin/routes/2 -H 'X-API-KEY: xyz' -X PUT -d '
{
  "name": "v1版API路由",
  "methods": ["GET"],
  "uris": ["/v1/hello", "/v1/hello/", "/v1/hello/*"],
  "upstream_id": 1,
  "plugin_config_id": 1
}'

现在系统中有两个路由：

• 非版本化路由：/hello
• 版本化路由：/v1/hello

实现旧版到新版的平滑迁移

为了引导用户迁移到新版 API，我们可以配置 301 重定向：

curl http://apisix:9180/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
  "plugins": {
    "redirect": {
      "uri": "/v1$uri",
      "ret_code": 301
    }
  }
}'

当用户访问旧版 API 时，将收到重定向响应：

curl http://apisix.org/hello

输出将是 301 重定向响应，引导用户访问新版 API。

最佳实践建议

1. 版本命名规范：保持版本号命名一致，如 v1、v2 等
2. 文档同步更新：每次发布新版本时，确保文档同步更新
3. 版本生命周期管理：明确每个版本的支持周期和废弃计划
4. 监控分析：监控各版本 API 的使用情况，为决策提供数据支持

总结

通过 Apache APISIX 实现多版本 API 管理具有以下优势：

1. 零停机迁移：通过重定向实现平滑过渡
2. 配置灵活：支持多种版本控制策略
3. 资源高效：无需为每个版本部署独立后端
4. 易于维护：集中管理所有版本的路由规则

掌握这些技巧后，您可以轻松应对 API 迭代过程中的各种挑战，为用户提供稳定可靠的服务体验。

apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/gh_mirrors/ap/apisix