Skip to main content
Version: 2.14

response-rewrite

描述#

response-rewrite 插件支持修改上游服务或 APISIX 返回的 Body 和 Header 信息。

该插件可以应用在以下场景中:

  • 通过设置 Access-Control-Allow-* 字段实现 CORS(跨域资源共享)的功能。
  • 通过设置标头中的 status_codeLocation 字段实现重定向。
tip

如果你仅需要重定向功能,建议使用 redirect 插件。

属性#

名称类型必选项默认值有效值描述
status_codeinteger[200, 598]修改上游返回状态码,默认保留原始响应代码。
bodystring修改上游返回的 body 内容,如果设置了新内容,header 里面的 content-length 字段也会被去掉。
body_base64booleanfalse描述 body 字段是否需要 base64 解码之后再返回给客户端,用在某些图片和 Protobuffer 场景。
headersobject返回给客户端的 headers,这里可以设置多个。头信息如果存在将重写,不存在则添加。想要删除某个 header 的话,把对应的值设置为空字符串即可。这个值能够以 $var 的格式包含 NGINX 变量,比如 $remote_addr $balancer_ip
varsarray[]vars 是一个表达式列表,只有满足条件的请求和响应才会修改 body 和 header 信息,来自 lua-resty-expr。如果 vars 字段为空,那么所有的重写动作都会被无条件的执行。
filtersarray[]一组过滤器,采用指定字符串表达式修改响应体。
filters.regexstring用于匹配响应体正则表达式。
filters.scopestring"once""once","global"替换范围,"once" 表达式 filters.regex 仅替换首次匹配上响应体的内容,"global" 则进行全局替换。
filters.replacestring替换后的内容。
filters.optionsstring"jo"正则匹配有效参数,可选项见 ngx.re.match
note

bodyfilters 属性只能配置其中一个。

启用插件#

你可以通过如下命令在指定路由上启用 response-rewrite 插件:

curl http://127.0.0.1:9080/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/test/index.html",
"plugins": {
"response-rewrite": {
"body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
"headers": {
"X-Server-id": 3,
"X-Server-status": "on",
"X-Server-balancer_addr": "$balancer_ip:$balancer_port"
},
"vars":[
[ "status","==",200 ]
]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:80": 1
}
}
}'

在上述命令中,通过配置 vars 参数可以让该插件仅在具有 200 状态码的响应上运行插件。

测试插件#

通过上述命令启用插件后,可以使用如下命令测试插件是否启用成功:

curl -X GET -i http://127.0.0.1:9080/test/index.html

无论来自上游的响应是什么,返回结果都是相同的:

HTTP/1.1 200 OK
Date: Sat, 16 Nov 2019 09:15:12 GMT
Transfer-Encoding: chunked
Connection: keep-alive
X-Server-id: 3
X-Server-status: on
X-Server-balancer_addr: 127.0.0.1:80

{"code":"ok","message":"new json body"}
IMPORTANT

ngx.exit 将会中断当前请求的执行并将其状态码返回给 NGINX。

如果你在 access 阶段执行了 ngx.exit,该操作只是中断了请求处理阶段,响应阶段仍然会处理。如果你配置了 response-rewrite 插件,它会强制覆盖你的响应信息(如响应代码)。

禁用插件#

当你需要禁用 response-rewrite 插件时,可以通过以下命令删除相应的 JSON 配置,APISIX 将会自动重新加载相关配置,无需重启服务:

curl http://127.0.0.1:9080/apisix/admin/routes/1  \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/test/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:80": 1
}
}
}'