apisix~proxy-rewrite 的 regex_uri 深度解析

APISIX 路由正则与 proxy-rewrite 的 regex_uri 深度解析

在 APISIX 中，proxy-rewrite 插件的 regex_uri 功能是实现复杂路由重写的核心工具。下面我将全面总结各种转发场景的使用方法和技巧。

regex_uri 基础语法

"regex_uri": ["匹配正则", "替换模板"]

• 匹配正则：PCRE 格式的正则表达式
• 替换模板 ：使用 $1, $2 等引用捕获组

常见转发场景总结

场景 1：简单前缀替换

"regex_uri": ["^/api/v1/(.*)", "/backend/$1"]

请求转换：

• /api/v1/users → /backend/users
• /api/v1/products/123 → /backend/products/123

场景 2：多段路径重组

"regex_uri": ["^/user/([^/]+)/profile/(.*)", "/profile/$1/$2"]

请求转换：

• /user/john/profile/settings → /profile/john/settings
• /user/mary/profile/preferences → /profile/mary/preferences

场景 3：版本号升级

"regex_uri": ["^/v1/(.*)", "/v2/$1"]

请求转换：

• /v1/orders → /v2/orders
• /v1/inventory/items → /v2/inventory/items

场景 4：路径参数提取

"regex_uri": ["^/product/(\\d+)/detail", "/items/$1"]

请求转换：

• /product/123/detail → /items/123
• /product/456/detail → /items/456

场景 5：多条件组合匹配

"regex_uri": ["^/(user|product)/(create|delete)/([a-z]+)", "/action/$2/$1/$3"]

请求转换：

• /user/create/account → /action/create/user/account
• /product/delete/item → /action/delete/product/item

场景 6：保留查询参数

"regex_uri": ["^/search/(.*)", "/query/$1"]

请求转换：

• /search/books?category=sci-fi → /query/books?category=sci-fi
• /search/movies?year=2023 → /query/movies?year=2023

场景 7：路径规范化

"regex_uri": ["^/([a-z]{2})/([a-z]+)/?$", "/$2/$1"]

请求转换：

• /en/home → /home/en
• /es/about → /about/es

场景 8：复杂重写模式

"regex_uri": ["^/(?:api|service)/v(\\d+)/(.*)", "/v$1/$2"]

请求转换：

• /api/v2/users → /v2/users
• /service/v3/products → /v3/products

高级应用场景

场景 9：条件重写（配合 vars）

"plugins": {
    "proxy-rewrite": {
        "regex_uri": ["^/user/(.*)", "/$1"],
        "vars": [
            ["http_x_api_version", "==", "v2"]
        ]
    }
}

仅当请求头 X-API-Version: v2 时生效

场景 10：多重正则组合

"plugins": [
    {
        "proxy-rewrite": {
            "regex_uri": ["^/api/", "/"]
        }
    },
    {
        "proxy-rewrite": {
            "regex_uri": ["^/v1/", "/v2/"]
        }
    }
]

分阶段重写：

1. /api/v1/users → /v1/users
2. /v1/users → /v2/users

场景 11：正则与直接 URI 重写结合

"plugins": {
    "proxy-rewrite": {
        "uri": "/new-base",
        "regex_uri": ["^/old/(.*)", "/$1"]
    }
}

组合效果：

• /old/path → /new-base/path
• /other → /new-base/other

性能优化技巧

1. 非捕获组优化 ：使用 (?:) 代替 () 避免不必要的捕获

   "regex_uri": ["^/(?:api|service)/v(\\d+)/(.*)", "/v$1/$2"]

2. 避免贪婪匹配 ：使用 .*? 代替 .* 防止过度匹配

   "regex_uri": ["^/category/(.*?)/(detail)", "/$2/$1"]

3. 精确锚定 ：使用 ^ 和 $ 限定匹配范围

   "regex_uri": ["^/exact/path$", "/new/exact"]

调试与测试方法

1. 使用 curl 测试

curl "http://127.0.0.1:9080/apisix/admin/plugin_metadata/proxy-rewrite" \
-H "X-API-KEY: your-admin-key" -X PUT -d '
{
    "regex_uri_debug": true
}'

2. 日志分析

在 error.log 中查看匹配详情：

2023/10/15 14:30:22 [debug] regex_uri match: pattern=^/api/(.*), uri=/api/v1/users, matches=1
2023/10/15 14:30:22 [debug] regex_uri replace: /api/v1/users -> /v1/users

3. 单元测试（Lua）

local rewrite = require("apisix.plugins.proxy-rewrite")
local ctx = {var = {uri = "/old/path"}}

rewrite.rewrite({regex_uri = {"^/old/(.*)", "/new/$1"}}, ctx)
ngx.say(ctx.var.uri) -- 输出: /new/path

常见问题解决方案

问题 1：正则不匹配

解决方案：

1. 使用在线正则测试器验证（如 regex101.com）
2. 添加调试日志 regex_uri_debug: true
3. 简化正则表达式，分步测试

问题 2：特殊字符转义

正确写法：

"regex_uri": ["^/search\\?q=(.+)", "/query/$1"]

问题 3：保留原始路径

"regex_uri": ["", "$0"] -- 保留完整原始路径

问题 4：大小写敏感问题

"regex_uri": ["(?i)^/api/(.*)", "/$1"] -- 忽略大小写

最佳实践

1. 路径标准化：在网关层统一路径格式

   "regex_uri": ["^/[A-Z]+/(.*)", "/${lower($1)}"]

2. 版本控制：无缝升级 API 版本

   "regex_uri": ["^/v1/(.*)", "/v2/$1"]

3. 多租户支持：

   "regex_uri": ["^/([a-z0-9]+)/api/(.*)", "/tenants/$1/$2"]

4. A/B 测试路由：

   "regex_uri": ["^/service/(.*)", "/service-v2/$1"],
   "vars": [["http_x_test_group", "==", "B"]]

5. 协议升级重定向：

   "plugins": {
       "proxy-rewrite": {
           "regex_uri": ["^(.*)", "https://new-domain.com$1"],
           "scheme": "https"
       }
   }

性能对比表

方法	复杂度	适用场景	性能影响
regex_uri	中-高	复杂路径转换	中（PCRE 编译）
uri 直接替换	低	简单前缀修改	低
多插件组合	高	分阶段处理	中-高
Nginx 原生 rewrite	中	深度定制	最低

建议：简单场景使用 uri 直接替换，复杂场景使用 regex_uri

自己项目中的使用

1. 静态改写，不需要正则

 "proxy-rewrite": {
      "uri": "/auth/realms/xx/protocol/openid-connect/token/introspect"
  }

2. 表达url一级路径的文件名，扩展名是.txt，例如:http://www.sina.com/1.txt

"proxy-rewrite": {
      "regex_uri": [
        "^/([^/]+\\.txt)$",
        "/auth/$1"
      ]
    }

3. 按前缀进行替换

"proxy-rewrite": {
    "regex_uri": [
        "^/user-xx(/.*)",
        "$1"
      ]
    }

4. 以某个前缀开头的，在转发时，在前缀前面添加固定字符，下面添加了apim-es到apim-admin的前面

"proxy-rewrite": {
     "regex_uri": [
        "\"^/apim-admin/(.*)\"",
        "/apim-es/$1"
      ]
    }