如何配置参数映射模板_SOFAStack API 统一网关(Sofa Apigateway)-阿里云帮助中心

API 网关支持通过配置参数映射模板的方式对请求和响应数据进行自动化修改。本文将详细介绍参数映射模板的配置语法及注意事项等。

模板示例

说明

后端 SOFAREST 协议已支持绑定参数映射。

请求模板

# 请求 body

{
 "x" : {"name": "jack"},
  "y" : {
   "z" : ["a", "b", "c"]
  }
}

# 定义参数
params:
  temp: $.Req.Header.temp
  body1: $.Req.Body.x
  body2: $.Req.Body.y
  bodyArray: $.Req.Body.y.z[0]
  body: $.Req.Body

# 表达式，会返回一个值，用于 mapping
expression: $.temp

# 映射规则
mappings:
  # 映射规则，至少一个
  ## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
  hello: // 若值为字符串类型的数值，需要加双引号，例如 "123"
    # 执行下面的映射逻辑
    ## body 覆盖模板 可选
    bodyOverride: '[{"name": "{{ $.temp }}"}, {"temp": {{ $.body1}}}]'
    ## request header 设置，先执行 delete，再执行 add 可选
    header:
      disableNormalizing: true
      addKeyValue:
        ah: $.temp
      deleteKey:
        - temp
    ## request cookie 设置，先执行 delete，再执行 add 可选
    cookie:
      addKeyValue:
        ac: $.temp
      deleteKey:
        - cookiekey
    ## request query 设置，先执行 delete，再执行 add 可选
    query:
      addKeyValue:
        aq: $.temp
      deleteKey:
        - querykey
  中文:
    # 执行下面的映射逻辑
    ## body 覆盖模板 可选
    bodyOverride: |
      [
       {"name": {{ $.body1 }}},
        {"temp": {{ $.body2}}},
        {"array":{{$.bodyArray}}},
        {"body": {{$.body}}}
      ]

# 默认映射规则
default:
  bodyOverride: '{"name": "{{ $.temp }}"}'
  header:
    addKeyValue:
      ah: $.temp
    deleteKey:
      - temp
  cookie:
    addKeyValue:
      ac: $.temp
    deleteKey:
      - cookiekey
  query:
    addKeyValue:
      aq: $.temp
    deleteKey:
      - querykey

响应模板

# 响应 body

{
 "x" : {"name": "jack"},
  "y" : {
   "z" : ["a", "b", "c"]
  }
}

# 定义参数
params:
    temp: $.Resp.Header.temp
    bodyx: $.Resp.Body.x
    bodyy: $.Resp.Body.y
    bodyArray: $.Resp.Body.y.z[0]
    body: $.Resp.Body

# 表达式，会返回一个值，用于 mapping
  expression: $.temp

# 映射规则
  mappings:
# 映射规则，至少一个
## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
    hello:
# 执行下面的映射逻辑
## body 覆盖模板 （可选操作）
      bodyOverride:|
[{"name":"{{ $.temp }}"},{"temp":{{ $.body1}}}]
## response header 设置，先执行 delete，再执行 add; （可选操作）
      header:
        addKeyValue:
          ah: $.temp
        deleteKey:
- temp
    world:
# 执行下面的映射逻辑
## body 覆盖模板; （可选操作）
      bodyOverride:|
"xx"

# 默认映射规则
default:
    bodyOverride:|
{"name":{{ $.temp }}}

如上示例所示，模板语法主要分为以下几个对象：

params：用于从请求或响应中提取参数。详见下文 params：提取参数。
expression：一个表达式，该表达式会返回一个值。详见下文 expression：表达式。
- 如果表达式是一个判断表达式，则返回 true/false。
- 如果表达式是一个字符串拼接，则返回一个字符串。
mappings：根据 expression 的返回内容，配置不同的映射规则。详见下文 mappings：映射规则。
default：（可选操作），存储一个默认的映射规则。

说明

默认的参数映射中，客户端获取的响应头是首字母大写的驼峰格式，您可以自定义添加 disableNormalizing 参数，并使其值为 true，这样客户端获取的响应头不经过转换，支持以小写格式直接透传到前端。

params：提取参数

params 可以从 request 或者 response 中提取参数，格式为 k:v。其中 key 为自定义的参数名，value 是一个参数表达式，格式为：$.Type.Location.key。

Type：可以是 Req 或者 Resp，分别表示请求和响应。
Location：可以是 Header、Query、Cookie 或者 Body。
- Resp 只支持 Header 和 Body。
- Body 必须为 JSON 格式。

示例

示例 1：从请求 Header 中提取参数

请求的 header：temp = headervalue

定义：temp = $.Req.Header.temp

结果：==> temp = headervalue

示例 2：从请求 Cookie 中提取参数

请求的 cookie：temp = cookievalue

定义：temp = $.Req.Cookie.temp

结果：==> temp = cookievalue

示例 3：从请求 Body 中提取参数

请求的 body：{"hello": {"world": ["1","2","3"]}}

定义：temp = $.Req.Body.hello.world[0]

结果：==> temp = 1

示例 4：从响应 Body 中提取参数

响应的 body：{"hello": {"world": ["1","2","3"]}}

定义：temp = $.Resp.Body.hello.world[0]

结果：==> temp = 1

expression：表达式

expression 表达式会返回一个值。表达式可以引用 params 中定义的变量，形式为 $.name。

示例 1

请求的 body：{"hello": {"world": ["1","2","3"]}}

定义：temp = $.Req.Body.hello.world[0]

表达式： $.temp == 1

结果：true

示例 2

请求的 cookie：temp = cookievalue

定义：temp = $.Req.Cookie.temp

表达式： $.temp

结果：cookievalue

mappings：映射规则

映射规则支持覆盖 Body、修改 Header、Query 和 Cookie。其中 Response 只支持修改 Body 和 Header。

覆盖 Body

bodyOverride 即覆盖 Body。值是 Go template 标准模板，可以通过 $.name 引用 params 中定义的变量。示例如下：

请求的 body：{"hello": {"world": ["1","2","3"]}}

定义：temp = $.Req.Body.hello.world[0]

bodyOverride： '{"name": "{{ $.temp }}"}'

结果：{"name":"1"}

其中，bodyOverride 是一个字符串模板，所以要用前后要加一个单引号。示例如下：

# 只能放在同一行，不能换行
bodyOverride: '{"name": "{{ $.name }}" }'

如果 bodyOverride 很长，一行放不下，可以使用以下方式多行输入。示例如下：

# 在 bodyOverride 后加一个 |，即可多行输入
# 换行输入要空两格，符合 yaml 标准语法
bodyOverride: |
    [
        {"name": {{ $.body1 }}},
        {"temp": {{ $.body2}}},
        {"array":{{$.bodyArray}}},
        {"body": {{$.body}}}
    ]

bodyOverride 的内容是一个 JSON 模板，要保证渲染后的结果是一个 JSON 字符串。

如果引用的参数变量是 String 类型，则需要使用 ""，如： {"name": "{{ $.string }}" }。
如果引用的参数变量是其他类型，则不需要 ""，如： {"name": {{ $.object }} }。

因此，配置模板时，必须确认参数的类型。示例如下：

假设 param.str = "jack"
定义 bodyOverride: '{"name": "{{ $.str }}" }'
渲染结果： {"name": "jack"}

符合标准 json

------------

假设 param.str = "jack"
定义 bodyOverride: '{"name": {{ $.str }} }'
渲染结果： {"name": jack}

不符合标准 json


------------

假设 param.obj = {"firstName":"tom"}
定义 bodyOverride: '{"name": {{ $.obj }} }'
渲染结果： {"name": {"firstName":"tom"}}

符合标准 json
------------

假设 param.obj = {"firstName":"tom"}
定义 bodyOverride: '{"name": "{{ $.obj }}" }'
渲染结果： {"name": "{\"firstName\":\"tom\"}"}

符合标准 json，但是不符合预期

修改 Query、Header、Cookie

这三个 key 均可以定义 addKeyValue 和 deleteKey。

addKeyValue：kv 结构，会在相应位置添加对应的 kv，通过 $.name 引用 params 中定义的变量。
deleteKey：list，会将定义的所有 key 从相应位置删除。

执行时，会先执行删除操作，再执行添加操作。示例如下：

请求的 cookie：temp = cookievalue

定义：temp = $.Req.Cookie.temp

映射：cookie:
		addKeyValue:
			newkey: $.temp
		delete:
			-	temp

结果：cookie: newkey = cookievalue