Apache APISIX 多版本 API 管理实战指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00635/article/details/148377618

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

apisix Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。项目地址: https://gitcode.com/gh_mirrors/api/apisix

什么是 API 版本控制？

API 版本控制是管理 API 变更并确保这些变更不会破坏客户端兼容性的实践。良好的版本控制策略能够清晰地传达变更内容，同时让 API 使用者能够自主决定何时升级到最新版本。

常见的 API 版本控制方式

1. URI 路径版本控制

最常见的版本控制方式是在 URI 路径中添加版本前缀（通常使用"v"前缀），通过 URI 路由将请求定向到特定版本的 API。

示例：

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

2. 查询参数版本控制

这种方式将版本号作为查询参数包含在 URI 中，而不是路径中。

示例：

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

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

通过在请求和响应中使用自定义头部来设置版本号，保持资源 URI 不变。

示例：

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

使用 Apache APISIX 实现多版本 API

准备工作

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

第一步：创建初始路由和上游

首先需要将 HTTP 请求从网关路由到上游服务（你的 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.apache.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 新版本

我们将采用 URI 路径版本控制方式，添加 v1 版本。

首先创建路径重写插件配置：

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

然后创建版本化路由：

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

现在系统中有两个路由：

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

第四步：将旧版请求重定向到新版

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

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 时，会收到 301 重定向响应：

curl http://apisix.apache.org/hello

输出：

<html>
<head><title>301 Moved Permanently</title></head>
<body>
<center><h1>301 Moved Permanently</h1></center>
<hr><center>openresty</center>
</body>
</html>