This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new f9537d184 docs: update proxy-rewrite plugin documentation (#13292)
f9537d184 is described below
commit f9537d18439ad791a5023ad280d487ed40e94220
Author: Yilia Lin <[email protected]>
AuthorDate: Wed Apr 29 09:08:38 2026 +0800
docs: update proxy-rewrite plugin documentation (#13292)
---
docs/en/latest/plugins/proxy-rewrite.md | 86 ++++++++++++++++++++++-
docs/zh/latest/plugins/proxy-rewrite.md | 120 +++++++++++++++++++++++++++-----
2 files changed, 187 insertions(+), 19 deletions(-)
diff --git a/docs/en/latest/plugins/proxy-rewrite.md
b/docs/en/latest/plugins/proxy-rewrite.md
index 68d85cc4f..d23ce9230 100644
--- a/docs/en/latest/plugins/proxy-rewrite.md
+++ b/docs/en/latest/plugins/proxy-rewrite.md
@@ -41,7 +41,7 @@ The `proxy-rewrite` Plugin offers options to rewrite requests
that APISIX forwar
| Name | Type | Required | Default | Valid
values
| Description
[...]
|-----------------------------|---------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
| uri | string | False | |
| New Upstream URI path. Value
supports [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For
example, `$arg_name`.
[...]
-| method | string | False | | ["GET",
"POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND",
"PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite
requests to use.
[...]
+| method | string | False | | ["GET",
"POST", "PUT", "HEAD", "DELETE", "OPTIONS", "MKCOL", "COPY", "MOVE",
"PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite
requests to use.
[...]
| regex_uri | array[string] | False | |
| Regular expressions used to
match the URI path from client requests and compose a new Upstream URI path.
When both `uri` and `regex_uri` are configured, `uri` has a higher priority.
The array should contain one or more **key-value pairs**, with the key being
the regular expression to m [...]
| host | string | False | |
| Set
[`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host)
request header.
[...]
| headers | object | False | |
| Header actions to be executed. Can
be set to objects of action verbs `add`, `remove`, and/or `set`; or an object
consisting of headers to be `set`. When multiple action verbs are configured,
actions are executed in the order of `add`, `remove`, and `set`.
|
@@ -505,3 +505,87 @@ curl -i "http://127.0.0.1:9080/get";
```
You should receive an `HTTP/1.1 403 Forbidden` response.
+
+### Dynamically Forward Requests in `radixtree_uri_with_parameter` Router Mode
+
+The following example demonstrates how to extract part of the URL path using
the `uri_param_*` variable and forward the value to the Upstream service in a
new header. This example assumes that APISIX is operating in the
`radixtree_uri_with_parameter` [router mode](../router-radixtree.md).
+
+Create a Route as such:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "httpbin",
+ "uri": "/anything/user/:user_id/profile",
+ "plugins": {
+ "proxy-rewrite": {
+ "headers": {
+ "set": {
+ "X-User-Id": "$uri_param_user_id"
+ }
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
+```
+
+`/anything/user/:user_id/profile` matches requests where `user_id` is a Route
parameter. The Plugin is configured to assign the `user_id` parameter value to
a new header `X-User-Id`.
+
+Send a request to the Route:
+
+```shell
+curl "http://127.0.0.1:9080/anything/user/123/profile";
+```
+
+You should see a response similar to the following:
+
+```text
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/8.6.0",
+ "X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",
+ "X-Forwarded-Host": "127.0.0.1",
+ "X-User-Id": "123"
+ },
+ ...
+}
+```
+
+The Route parameter also accepts URL-encoded strings. For instance, if you
send a request as such:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile";
+```
+
+The user ID would be extracted as `123 456`:
+
+```text
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/8.6.0",
+ "X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",
+ "X-Forwarded-Host": "127.0.0.1",
+ "X-User-Id": "123 456"
+ },
+ ...
+}
+```
diff --git a/docs/zh/latest/plugins/proxy-rewrite.md
b/docs/zh/latest/plugins/proxy-rewrite.md
index 58ba32ae4..42047dbd7 100644
--- a/docs/zh/latest/plugins/proxy-rewrite.md
+++ b/docs/zh/latest/plugins/proxy-rewrite.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- Proxy Rewrite
- proxy-rewrite
-description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP
方法、请求目标上游地址、请求标头等。
+description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，你可以修改 HTTP
方法、请求目标上游地址、请求标头等。
---
<!--
@@ -34,19 +34,19 @@ description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请
## 描述
-`proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP 方法、请求目标上游地址、请求标头等。
+`proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，你可以修改 HTTP 方法、请求目标上游地址、请求标头等。
## 属性
| 名称 | 类型 | 必需 | 默认值 | 有效值 | 描述 |
|-----------------------------|-----------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| uri | string | 否 | | | 新的上游 URI 路径。值支持 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。例如，`$arg_name`。 |
-| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE",
"OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK",
"PATCH", "TRACE"] | 要使用的重写请求的 HTTP 方法。 |
+| uri | string | 否 | | | 新的上游 URI 路径。值支持 [NGINX
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。例如，`$arg_name`。 |
+| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS",
"MKCOL", "COPY", "MOVE", "PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] |
要使用的重写请求的 HTTP 方法。 |
| regex_uri | array[string] | 否 | | | 用于匹配客户端请求的 URI 路径并组成新的上游 URI
路径的正则表达式。当同时配置 `uri` 和 `regex_uri` 时，`uri` 具有更高的优先级。该数组应包含一个或多个
**键值对**，其中键是用于匹配 URI 的正则表达式，值是新的上游 URI 路径。例如，对于 `["^/iresty/(. *)/(. *)",
"/$1-$2", ^/theothers/*", "/theothers"]`，如果请求最初发送到 `/iresty/hello/world`，插件会将上游
URI 路径重写为 `/iresty/hello-world`；如果请求最初发送到 `/theothers/hello/world`，插件会将上游 URI
路径重写为 `/theothers`。|
| host | string | 否 | | | 设置
[`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求标头。|
| headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set`
的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照“添加”、“删除”和“设置”的顺序执行。|
-| headers.add | object | 否 | | |
要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri`
的匹配结果（使用变量，例如 `$1-$2-$3`）。|
-| headers.set | object | 否 | | | 要设置请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量、一个或多个
[Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者
`regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。不应将其用于设置 `Host`。|
+| headers.add | object | 否 | | |
要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 [NGINX
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri`
的匹配结果（使用变量，例如 `$1-$2-$3`）。|
+| headers.set | object | 否 | | | 要设置请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量、一个或多个
[NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者
`regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。不应将其用于设置 `Host`。|
| headers.remove | array[string] | 否 | | | 从请求中删除的标头。
| use_real_request_uri_unsafe | boolean | 否 | false | | 如果为 True，则绕过 URI
规范化并允许完整的原始请求 URI。启用此选项被视为不安全。|
@@ -56,7 +56,7 @@ description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -66,7 +66,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
### 重写主机标头
-以下示例演示了如何修改请求中的 `Host` 标头。请注意，您不应使用 `headers.set` 来设置 `Host` 标头。
+以下示例演示了如何修改请求中的 `Host` 标头。请注意，你不应使用 `headers.set` 来设置 `Host` 标头。
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -95,7 +95,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/headers";
```
-您应该看到类似于以下内容的响应：
+你应该看到类似于以下内容的响应：
```text
{
@@ -146,7 +146,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/"; -H '"X-Api-Version": "v2"'
```
-您应该看到类似于以下内容的响应：
+你应该看到类似于以下内容的响应：
```text
{
@@ -209,7 +209,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/"; -H '"X-Api-Version": "v2"'
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
{
@@ -262,7 +262,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/headers";
```
-您应该看到类似以下的响应，其中 `User-Agen` 标头已被移除：
+你应该看到类似以下的响应，其中 `User-Agen` 标头已被移除：
```text
{
@@ -305,7 +305,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/test/user/agent";
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
{
@@ -344,7 +344,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/get";
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
{
@@ -396,7 +396,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/get";
```
-您应该会看到类似以下内容的响应：
+你应该会看到类似以下内容的响应：
```text
{
@@ -420,7 +420,7 @@ curl "http://127.0.0.1:9080/get";
### 将消费者名称转发到上游
-以下示例演示了如何将成功验证的消费者名称转发到上游服务。例如，您将使用 `key-auth` 作为身份验证方法。
+以下示例演示了如何将成功验证的消费者名称转发到上游服务。例如，你将使用 `key-auth` 作为身份验证方法。
创建消费者 `JohnDoe`：
@@ -480,7 +480,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/get"; -H 'apikey: john-key'
```
-您应该收到一个包含以下主体的 `HTTP/1.1 200 OK` 响应：
+你应该收到一个包含以下主体的 `HTTP/1.1 200 OK` 响应：
```text
{
@@ -504,4 +504,88 @@ curl -i "http://127.0.0.1:9080/get"; -H 'apikey: john-key'
curl -i "http://127.0.0.1:9080/get";
```
-您应该收到 `HTTP/1.1 403 Forbidden` 响应。
+你应该收到 `HTTP/1.1 403 Forbidden` 响应。
+
+### 在 `radixtree_uri_with_parameter` 路由模式下动态转发请求
+
+以下示例演示如何使用 `uri_param_*` 变量提取 URL 路径的一部分，并将其值转发到上游服务的新标头中。此示例假设 APISIX 运行在
`radixtree_uri_with_parameter` [路由模式](../router-radixtree.md)下。
+
+创建如下路由：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "httpbin",
+ "uri": "/anything/user/:user_id/profile",
+ "plugins": {
+ "proxy-rewrite": {
+ "headers": {
+ "set": {
+ "X-User-Id": "$uri_param_user_id"
+ }
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
+```
+
+`/anything/user/:user_id/profile` 匹配 `user_id` 为路由参数的请求。插件配置为将 `user_id`
参数值赋给新标头 `X-User-Id`。
+
+发送请求到路由：
+
+```shell
+curl "http://127.0.0.1:9080/anything/user/123/profile";
+```
+
+你应该看到类似于以下内容的响应：
+
+```text
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/8.6.0",
+ "X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",
+ "X-Forwarded-Host": "127.0.0.1",
+ "X-User-Id": "123"
+ },
+ ...
+}
+```
+
+路由参数也支持 URL 编码字符串。例如，发送如下请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile";
+```
+
+用户 ID 将被提取为 `123 456`：
+
+```text
+{
+ "args": {},
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/8.6.0",
+ "X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",
+ "X-Forwarded-Host": "127.0.0.1",
+ "X-User-Id": "123 456"
+ },
+ ...
+}
+```
