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

API7 网关 AI Agent Skill：API 版本管理方案

概览​

API 版本管理可以在引入新版本时继续支持旧客户端。在当前 API7 企业版模型中，请为每个后端版本创建一个服务，并使用 service_id 将路由关联到这些服务。

支持的模式：

  1. URI 路径版本管理：/v1/service、/v2/service。
  2. 基于请求头的版本管理：X-API-Version: 2。
  3. 渐进式发布：将一小部分流量发送到新版本。
  4. 版本弃用：重定向或返回受控响应。

方案 A：URI 路径版本管理​

1. 创建版本化服务​

a7 service create -g production -f - <<'EOF'
{
  "id": "service-v1",
  "name": "Service V1",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "v1-backend", "port": 8080, "weight": 1}
    ]
  }
}
EOF

a7 service create -g production -f - <<'EOF'
{
  "id": "service-v2",
  "name": "Service V2",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "v2-backend", "port": 8080, "weight": 1}
    ]
  }
}
EOF

2. 使用 URI 重写创建路由​

a7 route create -g production -f - <<'EOF'
{
  "id": "route-v1",
  "name": "route-v1",
  "paths": ["/v1/*"],
  "service_id": "service-v1",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/(.*)", "/$1"]
    }
  }
}
EOF

a7 route create -g production -f - <<'EOF'
{
  "id": "route-v2",
  "name": "route-v2",
  "paths": ["/v2/*"],
  "service_id": "service-v2",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v2/(.*)", "/$1"]
    }
  }
}
EOF

方案 B：基于请求头的版本管理​

该路由通过 service_id 默认指向 V1。匹配的请求可以使用 traffic-split 和内联上游路由到 V2。

a7 route create -g production -f - <<'EOF'
{
  "id": "versioned-api",
  "name": "versioned-api",
  "paths": ["/api/resource"],
  "service_id": "service-v1",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "match": [
            {"vars": [["http_x_api_version", "==", "2"]]}
          ],
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "v2-backend", "port": 8080, "weight": 1}]
              },
              "weight": 1
            }
          ]
        }
      ]
    }
  }
}
EOF

带有 X-API-Version: 2 的请求会发送到 V2，其他请求保留在 V1。

方案 C：渐进式版本发布​

在将 V2 设为默认版本前，先将一小部分 V1 流量切换到 V2。

a7 route update route-v1 -g production -f - <<'EOF'
{
  "service_id": "service-v1",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/(.*)", "/$1"]
    },
    "traffic-split": {
      "rules": [
        {
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "v2-backend", "port": 8080, "weight": 1}]
              },
              "weight": 1
            },
            {
              "weight": 9
            }
          ]
        }
      ]
    }
  }
}
EOF

未包含 upstream 的条目会回退到路由的默认服务。

通过重定向弃用版本​

a7 route update route-v1 -g production -f - <<'EOF'
{
  "paths": ["/v1/*"],
  "service_id": "service-v1",
  "plugins": {
    "redirect": {
      "regex_uri": ["^/v1/(.*)", "/v2/$1"],
      "ret_code": 301
    }
  }
}
EOF

配置同步​

version: "1"
services:
  - id: service-v1
    name: Service V1
    upstream:
      type: roundrobin
      nodes:
        - host: v1-svc
          port: 80
          weight: 1
  - id: service-v2
    name: Service V2
    upstream:
      type: roundrobin
      nodes:
        - host: v2-svc
          port: 80
          weight: 1
routes:
  - id: service-v1-route
    name: service-v1-route
    paths:
      - /v1/*
    service_id: service-v1
    plugins:
      proxy-rewrite:
        regex_uri: ["^/v1/(.*)", "/$1"]
  - id: service-v2-route
    name: service-v2-route
    paths:
      - /v2/*
    service_id: service-v2
    plugins:
      proxy-rewrite:
        regex_uri: ["^/v2/(.*)", "/$1"]

应用配置：

a7 config sync -g production -f versioning-config.yaml

验证​

curl -i https://gateway.prod.example.com/v1/health
curl -i https://gateway.prod.example.com/v2/health
curl -i -H "X-API-Version: 2" https://gateway.prod.example.com/api/resource
a7 route list -g production --service-id service-v1

重要注意事项​

  • 始终将服务和路由应用到目标 --gateway-group。
  • 当多个版本管理策略重叠时，使用路由优先级。
  • regex_uri 遵循 APISIX/Lua 兼容的正则行为。
  • 优先使用 service_id 进行默认路由，并为插件专用覆盖规则保留内联上游。

本页面由 api7/a7 仓库中的 a7-recipe-api-versioning/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。