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

改写代理请求

proxy-rewrite 插件允许你在客户端请求发送到上游服务之前修改该请求。它适用于修改 URI 路径、覆盖 HTTP 方法，或添加后端所需的强制请求头等任务。

前置条件​

  • API7 企业版实例正在运行。
  • 已创建网关组，并且网关实例正在运行。
  • 从控制台获取令牌。

改写静态 URI 路径​

你可以在请求到达上游之前替换整个 URI 路径。例如，将 /rewrite/get 改写为 /get。

curl -k "https://localhost:7443/apisix/admin/services/proxy-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proxy-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/static-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "static-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite/get"],
    "service_id": "proxy-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'

使用正则表达式改写​

正则改写更灵活，可用于剥离前缀或转换路径的一部分。例如，剥离 /rewrite-regex 前缀，使上游收到 /get。

curl -k "https://localhost:7443/apisix/admin/services/regex-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/regex-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regex-rewrite-route",
    "methods": ["GET"],
    "paths": ["/rewrite-regex/*"],
    "service_id": "regex-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "regex_uri": ["^/rewrite-regex/(.*)", "/$1"]
      }
    }
  }'

regex_uri 字段接收一组 [pattern, replacement] 配对数组。数组中第一个匹配的模式会用于改写。

修改请求头​

你可以在代理到上游之前添加、设置或移除请求头。这通常用于注入身份认证令牌，或移除敏感的客户端请求头。

curl -k "https://localhost:7443/apisix/admin/services/header-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/header-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "header-rewrite-route",
    "methods": ["GET"],
    "paths": ["/anything/headers-rewrite"],
    "service_id": "header-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "headers": {
          "set": {
            "X-Internal-Token": "secret-value"
          },
          "add": {
            "X-Added-Header": "example"
          },
          "remove": ["User-Agent"]
        }
      }
    }
  }'

请求头操作​

  • set：将请求头设置为指定值，并覆盖已有值。
  • add：向请求添加请求头，不覆盖已有值。
  • remove：从请求中移除指定请求头。

覆盖 HTTP 方法​

你可以为所有上游请求强制指定 HTTP 方法。例如，将 PUT 请求改为 POST 请求。

curl -k "https://localhost:7443/apisix/admin/services/method-rewrite-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/method-rewrite-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "method-rewrite-route",
    "paths": ["/anything/method-rewrite"],
    "service_id": "method-rewrite-service",
    "plugins": {
      "proxy-rewrite": {
        "method": "POST"
      }
    }
  }'

验证配置​

向已配置的路由发送请求，并观察响应或检查上游日志，以验证改写是否生效。

curl -i "http://127.0.0.1:9080/rewrite/get"

对于请求头改写示例，可以查看 httpbin 返回的上游请求头：

curl -s "http://127.0.0.1:9080/anything/headers-rewrite"

对于方法改写示例，发送 PUT 请求并确认上游看到的是 POST：

curl -s -X PUT "http://127.0.0.1:9080/anything/method-rewrite"

如果你配置了正则改写示例，向 http://127.0.0.1:9080/rewrite-regex/get 发送请求时，上游应收到 /get。

如果应用配置后路由立即返回 404，请等待几秒钟，让最新配置下发到网关后再重试。

故障排查​

  • 正则未匹配：确保正则模式正确，并在需要时覆盖完整 URI 路径。如果使用复杂模式，可以通过 pcregrep 等工具测试正则。
  • 请求头冲突：如果多个插件修改同一个请求头，执行顺序会影响结果。请确保 proxy-rewrite 相对于其他插件配置在合适的位置。
  • 无效 URI：uri 字段必须以 / 开头。如果配置时遇到 400 Bad Request，请检查 uri 语法。

后续步骤​