Response Transformer 响应变更插件

本文原文链接：https://docs.konghq.com/hub/kong-inc/response-transformer/

在将响应返回给客户端之前，转换上游服务器在Kong上发送的响应。

关于转换体的注意事项：注意响应体上转换的性能。为了解析和修改JSON主体，插件需要将其保留在内存中，这可能会在处理大型body（几个MB）时对工作者的Lua VM造成压力。由于Nginx的内部结构，在转换响应主体时不会设置Content-Length header。

术语

• plugin: 在请求被代理到上游API之前或之后，在Kong内部执行操作的插件。
• Service: 表示外部 upstream API或微服务的Kong实体。
• Route: 表示将下游请求映射到上游服务的方法的Kong实体。
• Consumer: 代表使用API的开发人员或机器的Kong实体。当使用Kong时，Consumer 仅与Kong通信，其代理对所述上游API的每次调用。
• Credential: 与Consumer关联的唯一字符串，也称为API密钥。
• upstream service: 这是指位于Kong后面的您自己的 API/service，转发客户端请求。

配置

此插件与具有以下协议的请求兼容：

• http
• https

此插件与无DB模式兼容。

在 Service 上启用插件

使用数据库：

通过发出以下请求在Service上配置此插件：

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=response-transformer"  \
    --data "config.remove.headers=x-toremove, x-another-one" \
    --data "config.remove.json=json-key-toremove, another-json-key" \
    --data "config.add.headers=x-new-header:value,x-another-header:something" \
    --data "config.add.json=new-json-key:some_value, another-json-key:some_value" \
    --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

不使用数据库：

通过添加此部分在服务上配置此插件执行声明性配置文件：

plugins:
- name: response-transformer
  service: {service}
  config: 
    remove.headers: x-toremove, x-another-one
    remove.json: json-key-toremove, another-json-key
    add.headers: x-new-header:value,x-another-header:something
    add.json: new-json-key:some_value, another-json-key:some_value
    append.headers: x-existing-header:some_value, x-another-header:some_value

在这两种情况下，{service}是此插件配置将定位的service的ID或name。

在 Route 上启用插件

使用数据库：

在Route上配置此插件：

$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=response-transformer"  \
    --data "config.remove.headers=x-toremove, x-another-one" \
    --data "config.remove.json=json-key-toremove, another-json-key" \
    --data "config.add.headers=x-new-header:value,x-another-header:something" \
    --data "config.add.json=new-json-key:some_value, another-json-key:some_value" \
    --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

不使用数据库：

通过添加此部分在路由上配置此插件执行声明性配置文件：

plugins:
- name: response-transformer
  route: {route}
  config: 
    remove.headers: x-toremove, x-another-one
    remove.json: json-key-toremove, another-json-key
    add.headers: x-new-header:value,x-another-header:something
    add.json: new-json-key:some_value, another-json-key:some_value
    append.headers: x-existing-header:some_value, x-another-header:some_value

在这两种情况下，{route}是此插件配置将定位的Route的ID或名称。

在 Consumer 上启用插件

使用数据库：

您可以使用http://localhost:8001/plugins在特定的Consumers上启用此插件:

$ curl -X POST http://kong:8001/consumers/{consumer}/plugins \
    --data "name=response-transformer" \
     \
    --data "config.remove.headers=x-toremove, x-another-one" \
    --data "config.remove.json=json-key-toremove, another-json-key" \
    --data "config.add.headers=x-new-header:value,x-another-header:something" \
    --data "config.add.json=new-json-key:some_value, another-json-key:some_value" \
    --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

不使用数据库：

通过添加此部分在Consumer上配置此插件执行声明性配置文件：

plugins:
- name: response-transformer
  consumer: {consumer}
  config: 
    remove.headers: x-toremove, x-another-one
    remove.json: json-key-toremove, another-json-key
    add.headers: x-new-header:value,x-another-header:something
    add.json: new-json-key:some_value, another-json-key:some_value
    append.headers: x-existing-header:some_value, x-another-header:some_value

在这两种情况下，{consumer}都是此插件配置将定位的Consumer的id或username。
您可以组合consumer_id和service_id 。 在同一个请求中，进一步缩小插件的范围。

全局插件

• 使用数据库： 可以使用http://kong:8001/plugins/配置所有插件。
• 不使用数据库： 可以通过plugins: 配置所有插件：声明性配置文件中的条目。

与任何 Service ，Route 或 Consumer （或API，如果您使用旧版本的Kong）无关的插件被视为“全局”，并将在每个请求上运行。有关更多信息，请阅读插件参考和插件优先级部分。

参数

以下是可在此插件配置中使用的所有参数的列表：

注意：如果值包含a，则不能使用列表的逗号分隔格式。必须使用数组表示法。

执行顺序

插件按以下顺序执行响应变更：
删除 -> 重命名 -> 替换 -> 添加 ->追加
remove –> rename –> replace –> add –> append

例子

在这些示例中，我们在Route上启用了插件。这对于Service来说同样适用。

• 通过分别传递每个header：键值对来添加多个header：

使用数据库：

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers[1]=h1:v1" \
  --data "config.add.headers[2]=h2:v1"

不使用数据库：

plugins:
- name: response-transformer
  route: {route}
  config:
    add:
      headers: ["h1:v1", "h2:v2"]

• 通过传递逗号分隔的标头：值对来添加多个标头（仅适用于数据库）：

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers=h1:v1,h2:v2"

• 添加多个标头，将config作为JSON主体传递（仅适用于数据库）：

  $ curl -X POST http://localhost:8001/routes/{route}/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "response-transformer", "config": {"add": {"headers": ["h1:v2", "h2:v1"]}}}'

• 添加body属性和header：

使用数据库：

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.json=p1:v1,p2=v2" \
  --data "config.add.headers=h1:v1"

不使用数据库：

plugins:
- name: response-transformer
  route: {route}
  config:
    add:
      json: ["p1:v1", "p2=v2"]
      headers: ["h1:v1"]

• 附加多个标头并删除body参数：

使用数据库：

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "response-transformer", "config": {"append": {"headers": ["h1:v2", "h2:v1"]}, "remove": {"json": ["p1"]}}}'

不使用数据库：

plugins:
- name: response-transformer
  route: {route}
  config:
    append:
      headers: ["h1:v2", "h2:v1"]
    remove:
      json: ["p1"]