跳到主要内容

Response Transformer

概述​

响应转换器策略是一种出站策略，它在将响应传递给客户端之前，修改从上游服务返回的响应。此转换允许：

  • 添加、删除、替换、重命名或附加响应头或 JSON 字段。
  • 过滤或重构响应主体。
  • 掩盖或转换敏感字段。
  • 确保不同服务之间响应负载的一致性。

当您想要隐藏内部实现细节或使 API 响应与外部客户端合同对齐时，这尤其有用。

备注

此插件与无数据库模式兼容，并支持 grpc、grpcs、http 和 https 协议。

配置详情​

配置使用简单的键值格式来声明转换操作。每个操作在特定命名空间下定义，并支持头部和 JSON 主体字段。

转换顺序​

转换按以下顺序执行：

  1. 删除
  2. 重命名
  3. 替换
  4. 添加
  5. 附加

支持的转换字段​

Field Description
remove删除特定的响应头或 JSON 键
rename重命名现有的响应头或 JSON 键
replace替换现有响应头或 JSON 键的值
add添加新的响应头或 JSON 字段（如果已存在则替换现有字段）
append向现有头部或 JSON 数组附加额外值

关键配置选项​

FieldDescription
config.add.headers添加新的响应头。格式：header-name:value
config.add.json将新的 JSON 键添加到响应体中。格式：key:value
config.add.json_types在使用 add 或 append 时，显式设置 JSON 值类型（字符串、布尔值、数字）。
config.append.headers将值附加到现有的头部。格式：header-name:value
config.append.json将值附加到现有的 JSON 键。
config.remove.headers移除现有的响应头。格式：header-name
config.remove.json从响应中移除特定的 JSON 键。
config.rename.headers重命名头部。格式：old-name:new-name
config.rename.json重命名 JSON 键。格式：old-key:new-key
config.replace.headers替换头部值。格式：header-name:new-value
config.replace.json替换 JSON 键值。格式：key:new-value
config.replace.json_types在用非字符串类型（布尔值、数字）替换 JSON 值时是必需的。

示例​

基本示例 - 添加头部和 JSON 键​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"add": {
				"headers": ["x-new-header:value", "x-another-header:something"],
				"json": ["new-json-key:some_value", "another-json-key:some_value"],
				"json_types": ["string", "boolean", "number"]
		}
	}
}'

附加头部并移除 JSON 字段​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"append": {
				"headers": ["x-header-1:v2", "x-header-2:v1"]
			},
			"remove": {
				"json": ["internal-field"]
		}
	}
}'

重命名 JSON 键和头部​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--data "name=response-transformer" \
	--data "config.rename.headers=old-header:new-header" \
	--data "config.rename.json=old-key:new-key"

带有多个操作的完整示例​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"remove": {
				"headers": ["x-toremove", "x-another-one"],
				"json": ["json-key-toremove", "another-json-key"]
		},
		"add": {
			"headers": ["x-new-header:value"],
			"json": ["new-json-key:some_value"],
			"json_types": ["string"]
		},
		"append": {
			"headers": ["x-existing-header:some_value", "x-another-header:some_value"]
		}
	}
}'

其他说明​

  • 如果一个值包含逗号 (,) ，则必须使用数组表示法（例如，JSON 数组）。
  • 此插件在转换期间会将整个响应体保留在内存中，这可能会影响大响应的性能。
  • 在转换 gzip 压缩的有效负载时，请确保正确处理 Content-Encoding: gzip 头。
  • 此插件不会修改 Nginx 写入的 x-forwarded-* 头。
  • JSON 键值类型 (json_types) 在附加或添加数字或布尔字段时至关重要。

有关使用该策略的更多说明和高级示例，请参阅本指南：响应转换器 - 插件 | Kong 文档