Request Transformer

概述

请求转换器策略是一种入站策略，它允许在将传入的 HTTP 请求转发到上游服务之前动态修改这些请求。这包括以下功能：

• 移除或添加头部、查询字符串和主体参数。
• 重命名或替换特定的请求字段。
• 使用模板或静态值应用转换逻辑。

这在将 API 适配到遗留系统、添加或掩盖敏感信息，或支持不断发展的 API 合同等场景中非常有用。

Kong Gateway 按以下顺序处理请求转换：

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

配置详情

用户界面提供动态配置输入。您可以通过单击绿色加号图标添加多个转换行。

支持的转换类型

Field	Format	Description
config.remove.headers	x-remove-header	移除指定的头部。
config.remove.querystring	param1,param2	移除特定的查询参数。
config.remove.body	param1,param2	移除特定的表单字段。
config.rename.headers	old:new	重命名一个头部。
config.rename.querystring	old:new	重命名一个查询参数。
config.rename.body	old:new	重命名一个主体字段。
config.replace.headers	key:value	替换头部值。
config.replace.querystring	key:value	替换查询参数值。
config.replace.body	key:value	替换主体字段值。
config.add.headers	key:value	添加一个新头部。
config.add.querystring	key:value	添加一个新查询参数。
config.add.body	key:value	添加一个新表单字段。
config.append.headers	key:value	附加到现有的头部值。
config.append.querystring	key:value	附加到现有的查询参数值。
config.append.body	key:value	附加到现有的主体参数值。

• 如果字段的值包含逗号，请使用数组表示法，而不是逗号分隔的字符串。

例如，headers[1]=h1:v1

• x-forwarded-* 头部（由 Nginx 添加）无法通过此插件进行修改。
• 对于所有配置类型，列表项必须遵循 "key:value" 格式或 "old:new" 用于重命名。

模板

您可以使用模板动态注入来自传入请求的值：

头部：

${headers.<header_name>}

查询：

${query_params.<param_name>}

URI 捕获：

${uri_captures.<group_name>}

共享：

${shared.<variable_name>}

您甚至可以在模板中使用 Lua 表达式，如下所示：

Authorization:$(function()
	local value = headers.Authorization
	if not value then return end
	if value:sub(1,6) == "Basic " then return value end
	return "Basic " .. value
end())

示例

基本请求转换

通过删除一个头部、重命名一个主体字段和添加一个查询参数来转换传入请求：

{
	"name": "request-transformer",
	"config": {
		"remove": {
		"headers": ["x-remove-header"],
		"body": ["formparam-toremove"],
		"querystring": ["qs-toremove"]
		},
		"rename": {
		"body": ["param-old:param-new"]
		},
		"add": {
		"querystring": ["new-param:some_value"],
		"headers": ["x-new-header:some_value"]
		}
	}
}

通过 Kong 管理 API 启用

curl -X POST [http://localhost:8001/services/{serviceName}/plugins](http://localhost:8001/services/%7BserviceName%7D/plugins) \
--data "name=request-transformer" \
--data "config.add.body=new-field:defaultvalue"

在一个请求中附加和删除

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
--data "name=request-transformer" \
--data "config.append.headers=h1:v2,h2:v1" \
--data "config.remove.body=p1"

使用 URI 捕获模板

--data "config.add.headers=x-user-id:${uri_captures['user_id']}"

多个头部（作为数组）

--data "config.add.headers[1]=h1:v1" \
--data "config.add.headers[2]=h2:v1"

此插件具有高度灵活性，并在弥合客户期望与上游 API 规范之间的差异中发挥着关键作用。

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