response-rewrite

描述

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

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

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

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

属性

名称类型必选项默认值有效值描述
status_codeinteger[200, 598]修改上游返回状态码,默认保留原始响应代码。
bodystring修改上游返回的 body 内容,如果设置了新内容,header 里面的 content-length 字段也会被去掉。
body_base64booleanfalse当设置时,在写给客户端之前,在body中传递的主体将被解码,这在一些图像和 Protobuffer 场景中使用。注意,这个字段只允许对插件配置中传递的主体进行解码,并不对上游响应进行解码。
headersobject
headers.addarray添加新的响应头。格式为 [“name: value”, …]。这个值能够以 $var 的格式包含 NGINX 变量,比如 $remote_addr $balancer_ip
headers.setobject改写响应头。格式为 {“name”: “value”, …}。这个值能够以 $var 的格式包含 NGINX 变量,比如 $remote_addr $balancer_ip
headers.removearray移除响应头。格式为 [“name”, …]
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

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

启用插件

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

  1. curl http://127.0.0.1:9180/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. "set": {
  11. "X-Server-id": 3,
  12. "X-Server-status": "on",
  13. "X-Server-balancer-addr": "$balancer_ip:$balancer_port"
  14. }
  15. },
  16. "vars":[
  17. [ "status","==",200 ]
  18. ]
  19. }
  20. },
  21. "upstream": {
  22. "type": "roundrobin",
  23. "nodes": {
  24. "127.0.0.1:80": 1
  25. }
  26. }
  27. }'

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

除了 set 操作,你也可以像这样增加或移除响应头:

  1. "headers": {
  2. "add": [
  3. "X-Server-balancer-addr: $balancer_ip:$balancer_port"
  4. ],
  5. "remove": [
  6. "X-TO-BE-REMOVED"
  7. ]
  8. }

这些操作的执行顺序为 [“add”, “set”, “remove”]。

我们不再对直接在 headers 下面设置响应头的方式提供支持。 如果你的配置是把响应头设置到 headers 的下一层,你需要将这些配置移到 headers.set

测试插件

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

  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
  8. {"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_filterngx.exit
body_filter×ngx.exit

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

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

删除插件

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

  1. curl http://127.0.0.1:9180/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. }'