response-rewrite

描述

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

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

  • 通过设置 Access-Control-Allow-* 字段实现 CORS（跨域资源共享）的功能。
  • 通过设置标头中的 status_code 和 Location 字段实现重定向。
response-rewrite - 图1tip

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

属性

名称类型必选项默认值有效值描述
status_codeinteger否[200, 598]修改上游返回状态码，默认保留原始响应代码。
bodystring否修改上游返回的 body 内容，如果设置了新内容，header 里面的 content-length 字段也会被去掉。
body_base64boolean否false描述 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。
response-rewrite - 图2note

body 和 filters 属性只能配置其中一个。

启用插件

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

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uri": "/test/index.html",
  6.     "plugins": {
  7.         "response-rewrite": {
  8.             "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
  9.             "headers": {
  10.                 "X-Server-id": 3,
  11.                 "X-Server-status": "on",
  12.                 "X-Server-balancer_addr": "$balancer_ip:$balancer_port"
  13.             },
  14.             "vars":[
  15.                 [ "status","==",200 ]
  16.             ]
  17.         }
  18.     },
  19.     "upstream": {
  20.         "type": "roundrobin",
  21.         "nodes": {
  22.             "127.0.0.1:80": 1
  23.         }
  24.     }
  25. }'

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

测试插件

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

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

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

  1. HTTP/1.1 200 OK
  2. Date: Sat, 16 Nov 2019 09:15:12 GMT
  3. Transfer-Encoding: chunked
  4. Connection: keep-alive
  5. X-Server-id: 3
  6. X-Server-status: on
  7. X-Server-balancer_addr: 127.0.0.1:80
  9. {"code":"ok","message":"new json body"}
response-rewrite - 图3IMPORTANT

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

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

Phaserewriteaccessheader_filterbody_filter
rewritengx.exit√√√
access×ngx.exit√√
header_filter√√ngx.exit√
body_filter√√×ngx.exit

使用 filters 正则匹配将返回 body 的 X-Amzn-Trace-Id 替换为 X-Amzn-Trace-Id-Replace。

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.   "plugins":{
  4.     "response-rewrite":{
  5.       "headers":{
  6.         "X-Server-id":3,
  7.         "X-Server-status":"on",
  8.         "X-Server-balancer_addr":"$balancer_ip:$balancer_port"
  9.       },
  10.       "filters":[
  11.         {
  12.           "regex":"X-Amzn-Trace-Id",
  13.           "scope":"global",
  14.           "replace":"X-Amzn-Trace-Id-Replace"
  15.         }
  16.       ],
  17.       "vars":[
  18.         [
  19.           "status",
  20.           "==",
  21.           200
  22.         ]
  23.       ]
  24.     }
  25.   },
  26.   "upstream":{
  27.     "type":"roundrobin",
  28.     "scheme":"https",
  29.     "nodes":{
  30.       "httpbin.org:443":1
  31.     }
  32.   },
  33.   "uri":"/*"
  34. }'
  1. curl -X GET -i  http://127.0.0.1:9080/get
  1. HTTP/1.1 200 OK
  2. Transfer-Encoding: chunked
  3. X-Server-status: on
  4. X-Server-balancer-addr: 34.206.80.189:443
  5. X-Server-id: 3
  7. {
  8.   "args": {},
  9.   "headers": {
  10.     "Accept": "*/*",
  11.     "Host": "127.0.0.1",
  12.     "User-Agent": "curl/7.29.0",
  13.     "X-Amzn-Trace-Id-Replace": "Root=1-629e0b89-1e274fdd7c23ca6e64145aa2",
  14.     "X-Forwarded-Host": "127.0.0.1"
  15.   },
  16.   "origin": "127.0.0.1, 117.136.46.203",
  17.   "url": "https://127.0.0.1/get"
  18. }

禁用插件

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

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1  \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uri": "/test/index.html",
  6.     "upstream": {
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:80": 1
  10.         }
  11.     }
  12. }'