请求响应转换
更新时间：2026-09-20
概述
请求响应转换插件用于在网关侧对请求与响应进行改写，可以对请求头、响应头、请求查询参数、请求体参数、响应体参数进行转换，帮助您在不改动客户端与后端代码的情况下完成协议字段适配、灰度标记注入、敏感字段剔除等场景。
生效范围：基础 API / Model API / Agent API。
支持的转换对象与操作
| 转换对象 | 说明 |
|---|---|
| 请求头（Request Header） | 转发到后端前改写请求头。 |
| 请求查询参数（Request Query） | 转发到后端前改写 URL 上的查询参数。 |
| 请求体参数（Request Body） | 转发到后端前改写请求体中的参数。 |
| 响应头（Response Header） | 返回客户端前改写响应头。 |
| 响应体参数（Response Body） | 返回客户端前改写响应体中的参数。 |
每类转换对象均支持以下操作类型：
| 操作类型 | 说明 |
|---|---|
| 删除（remove） | 删除指定的参数或头。 |
| 重命名（rename） | 保留值，将参数或头的名称改为新名称。 |
| 更新（replace） | 将指定参数或头的值替换为新值。 |
| 添加（add） | 参数或头不存在时新增；已存在时不覆盖。 |
| 追加（append） | 在已有值的基础上追加一个值，形成多值。 |
| 映射（map） | 将来源参数或头的值复制到目标参数或头。 |
| 去重（dedupe） | 对多值的参数或头做去重处理。 |
配置方式
在插件配置中填写 reqRules 或 respRules，至少配置其中一项。每项由一组转换规则组成：
YAML
1reqRules:
2 - operate: replace
3 headers:
4 - key: x-tenant
5 newValue: production
6respRules:
7 - operate: add
8 body:
9 - key: meta.source
10 value: gateway
11 value_type: string顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
reqRules |
array of object | 请求转换规则，支持请求 Header、Query 和 Body |
respRules |
array of object | 响应转换规则，支持响应 Header 和 Body；响应不支持 Query |
规则字段
| 字段 | 适用操作 | 说明 |
|---|---|---|
operate |
全部 | remove、rename、replace、add、append、map、dedupe |
mapSource |
map |
映射来源：headers、querys 或 body。不填写时表示在同一类对象内映射 |
headers |
全部 | Header 转换规则数组 |
querys |
请求阶段 | Query 转换规则数组 |
body |
全部 | Body 转换规则数组 |
字段规则
| 字段 | 适用操作 | 说明 |
|---|---|---|
key |
remove、replace、add、append、dedupe |
目标 Header、Query 名称或 JSON 路径 |
oldKey |
rename |
需要重命名的名称或 JSON 路径 |
newKey |
rename |
新的名称或 JSON 路径 |
newValue |
replace |
更新后的值 |
value |
add |
新增值 |
appendValue |
append |
追加值 |
fromKey |
map |
映射来源名称或 JSON 路径 |
toKey |
map |
映射目标名称或 JSON 路径 |
value_type |
JSON Body | string、number、boolean、object；默认按字符串写入 |
strategy |
dedupe |
RETAIN_FIRST、RETAIN_LAST、RETAIN_UNIQUE |
host_pattern |
replace、add、append |
按请求 Host 匹配，并支持 $1、$2 等捕获组 |
path_pattern |
replace、add、append |
按请求路径匹配，并支持 $1、$2 等捕获组 |
同一条规则同时配置 host_pattern 和 path_pattern 时，以 host_pattern 为准。两个字段使用正则表达式。
操作说明
| 操作 | 使用方式 |
|---|---|
remove |
删除指定名称的全部值；目标不存在时不处理 |
rename |
把 oldKey 改为 newKey；目标已存在时保留目标值 |
replace |
更新已有字段；字段不存在时不新增 |
add |
字段不存在时新增；字段已存在时不覆盖 |
append |
在已有字段后追加一个值；字段不存在时直接新增 |
map |
把来源字段值复制到目标字段，目标已有值会被覆盖，来源字段保留 |
dedupe |
对同名字段去重。RETAIN_FIRST 保留第一个，RETAIN_LAST 保留最后一个，RETAIN_UNIQUE 保留所有唯一值 |
规则执行顺序固定为：
remove → rename → replace → add → append → map → dedupe
支持范围
| 内容 | 请求 | 响应 |
|---|---|---|
| Header | 支持 | 支持 |
| Query | 支持 | 不支持 |
application/json |
支持 | 支持 |
application/*+json |
支持 | 支持 |
application/x-www-form-urlencoded |
支持 | 不支持 |
multipart/form-data |
支持普通字段 | 不支持 |
请求 Body 的 multipart/form-data 只修改普通表单字段，不修改文件内容、文件名和文件顺序。带 gzip、br 等压缩编码的 Body 不做转换；SSE、WebSocket、gRPC 和 CONNECT 请求不做转换。
配置示例
转换请求 Header
YAML
1reqRules:
2 - operate: remove
3 headers:
4 - key: x-debug
5 - operate: rename
6 headers:
7 - oldKey: x-old-tenant
8 newKey: x-tenant
9 - operate: replace
10 headers:
11 - key: x-tenant
12 newValue: production
13 - operate: add
14 headers:
15 - key: x-source
16 value: gateway
17 - operate: append
18 headers:
19 - key: x-trace
20 appendValue: transformer转换请求 Query
YAML
1reqRules:
2 - operate: remove
3 querys:
4 - key: debug
5 - operate: rename
6 querys:
7 - oldKey: tenant
8 newKey: tenant_id
9 - operate: replace
10 querys:
11 - key: tenant_id
12 newValue: production
13 - operate: add
14 querys:
15 - key: source
16 value: gateway
17 - operate: append
18 querys:
19 - key: trace
20 appendValue: transformer转换请求 JSON Body
YAML
1reqRules:
2 - operate: replace
3 body:
4 - key: user.id
5 newValue: 1001
6 value_type: number
7 - operate: add
8 body:
9 - key: source
10 value: gateway
11 value_type: string
12 - operate: append
13 body:
14 - key: tags
15 appendValue: transformed
16 value_type: string请求 Body：
JSON
1{"user":{"id":1},"tags":["original"]}转换后：
JSON
1{"user":{"id":1001},"tags":["original","transformed"],"source":"gateway"}转换 Form Body
YAML
1reqRules:
2 - operate: rename
3 body:
4 - oldKey: user
5 newKey: user_name
6 - operate: replace
7 body:
8 - key: tenant
9 newValue: production
10 - operate: add
11 body:
12 - key: source
13 value: gateway请求头需要设置 Content-Type: application/x-www-form-urlencoded。
响应转换示例
响应转换只修改响应 Header 和 JSON Body：
YAML
1respRules:
2 - operate: replace
3 headers:
4 - key: x-backend-version
5 newValue: transformed
6 - operate: replace
7 body:
8 - key: ok
9 newValue: false
10 value_type: boolean
11 - operate: add
12 body:
13 - key: meta.source
14 value: gateway
15 value_type: string
16 - operate: remove
17 body:
18 - key: debug跨字段映射
map 可以把 Header、Query 或 Body 中的字段写入另一类对象。
来源 mapSource |
可写入目标 | 常见用途 |
|---|---|---|
headers |
Header、Query、Body | 把请求 Header 传给后端参数 |
querys |
Header、Query、Body | 把 URL 参数写入 Header 或 Body |
body |
Header、Query、Body | 根据 Body 参数匹配路由或补充 Header |
根据 Body 参数匹配路由
YAML
1reqRules:
2 - operate: map
3 mapSource: body
4 headers:
5 - fromKey: userId
6 toKey: x-user-idJSON 请求：
Bash
1curl -i -X POST https://gateway.example.com/api/orders \
2 -H 'Content-Type: application/json' \
3 -d '{"userId":12,"userName":"johnlanni"}'插件会把 Body 中的 userId 写入 x-user-id，网关可以根据该 Header 选择路由。application/x-www-form-urlencoded 请求也支持同样的配置：
Bash
1curl -i -X POST https://gateway.example.com/api/orders \
2 -H 'Content-Type: application/x-www-form-urlencoded' \
3 --data 'userId=12&userName=johnlanni'Header 写入 JSON Body
YAML
1reqRules:
2 - operate: map
3 mapSource: headers
4 body:
5 - fromKey: x-user-id
6 toKey: user.id响应 Body 写入 Header
YAML
1respRules:
2 - operate: map
3 mapSource: body
4 headers:
5 - fromKey: requestId
6 toKey: x-request-id响应 JSON 中存在 requestId 时，会增加 x-request-id 响应 Header。
JSON 路径和值类型
JSON 路径使用点号表示嵌套：
user.id：访问user对象下的id；users.0.name：访问数组第一个元素；users.#.age：遍历数组中每个元素的age，建议只用于replace；foo\.bar：访问名称本身包含点号的字段（JSON 字符串中写作foo\\.bar）。
value_type 只对 JSON Body 生效：
| 值类型 | 写入结果 | 示例 |
|---|---|---|
string |
字符串 | "1001" |
number |
数字 | 1001 |
boolean |
布尔值 | true |
object |
JSON 对象或数组 | {"level":"gold"} |
条件匹配和捕获组
YAML
1reqRules:
2 - operate: add
3 headers:
4 - key: x-route-group
5 value: group-$1
6 host_pattern: '^api-([^.]+)\.example\.com$'
7 - operate: add
8 querys:
9 - key: path_group
10 value: group-$1
11 path_pattern: '^/v1/([^/?]+)'当 Host 为 api-blue.example.com 时，会增加 x-route-group: group-blue；当路径为 /v1/orders 时，会增加 path_group=group-orders。
为后端注入固定请求头并剔除敏感头
YAML
1request:
2 headers:
3 add:
4 - key: X-Gateway-Source
5 value: apigw
6 remove:
7 - X-Internal-Token重命名查询参数以适配后端接口
YAML
1request:
2 querys:
3 rename:
4 - from: userId
5 to: uid向客户端响应中补充追踪头
YAML
1response:
2 headers:
3 add:
4 - key: X-Trace-Id
5 value: "%REQ(x-request-id)%"说明：以上示例展示配置思路，实际字段结构请参照插件市场中该插件详情页「文档」标签页给出的参数说明。
使用限制
- 插件基于完整的请求体/响应体生效，不支持修改 SSE（流式输出）接口的响应体内容。大模型流式调用场景下，请求侧转换正常生效，响应体转换不生效。
- 对请求体/响应体的转换要求报文为可解析的结构化格式（如 JSON），非结构化报文仅支持头与查询参数的转换。
- 转换操作会带来额外的报文解析开销，请避免在大报文接口上配置过多的体参数转换规则。
相关操作
评价此篇文章