参数映射与校验规则

1. 概述

API网关支持参数映射与校验逻辑，本篇文档描述了API网关对转发客户端发起的HTTP请求到HTTP后端服务，以及转发后端服务的HTTP应答到客户端的处理规则，后端为阿里云函数计算的用户请参考函数计算。

目前API网关支持以下几种传输处理方式：

• 入参透传模式：API网关除Path位置的请求参数外，不对其他位置的请求参数进行映射与校验，用户参数会透明传递给后端，详细请阅读章节3。

• 入参映射（过滤未知参数）模式：API网关会根据用户配置的所有参数执行校验与映射，如果客户端传递了未在配置中的参数，参数将会被API网关过滤掉，不会转发给后端，详细请参考章节4。

• 入参映射（透传未知参数）模式：在此模式下，如果用户传递了未配置的参数，参数会被透传给后端，详细请参考章节5。

2. 参数位置与读取规则

API网关支持从HTTP请求的各种位置上读取参数，以及API网关提供的系统参数与用户可配置的常量参数。

2.1. path参数

API网关支持从HTTP请求的分段路径中提取参数的能力，使用path参数，需要首先将API的请求路径配置为/path/[parameter]的格式，API网关会使用参数路径方式去匹配HTTP请求中的路径，请参考如下的例子：

- API网关对于不符合RFC3986的非法输入，直接返回错误码：I400PH: Invalid Request Path- API网关支持的最大RequestUri长度为128KBytes, 超过这个限制时会返回错误码：I413RL: Request Url too Large

2.2. query参数

query参数为请求在QueryString中携带的参数，API网关会对请求QueryString通过=与&分割符进行键值对的拆分，并使用UTF-8编码做Url Decode，对于?a=和?a均被认为是值等于空字符串''的合法值，如：

• *API网关对于不符合RFC3986的非法输入，直接返回错误码：I400PH: Invalid Request Path

• *API网关支持的最大RequestUri长度为128KBytes, 超过这个限制时会返回错误码：I413RL: Request Url too Large

2.3. formData参数

formData参数为当请求的Content-Type为application/x-www-form-urlencoded时，消息体中携带的值。如果Content-Type没有指定charset=则网关会使用UTF-8编码，否则使用charset中指定的字符集来进行Url Decode，对于Form的拆分与处理逻辑与QueryString中描述的处理方式一致。

当Content-Type为multipart/formdata时，网关支持进行文件类型参数。

2.4. header参数

header参数会从HTTP请求的头中读取，比如X-User: aaa会被解析为X-User=aaa，特殊规则如下

• Header值中包含的前后空格会被截取掉

• 如果存在多个重名Header且参数类型被配置为ARRAY则参数会被解析为数组，否则只取第一个值

• API网关使用ISO-8859-1编码读取和转发Header，非法字符会导致乱码或其他非预期的结果

2.5. host参数

host参数仅在用户绑定了泛域名和有效的泛域名模板时才有效，例如：绑定泛域名*.api.foo.com且配置了泛域名模板${user}.api.foo.com，则当收到请求1234.api.foo.com时，会读取到host参数user=1234，用户可以配置多个泛域名模板，API网关会使用第一个匹配到的记录来解析host参数，如果没有记录，则不会读取到host参数，具体例子如下

在最后一个例子中，因为第一条记录就已经命中匹配了，所以忽略后面的所有记录。

3. 入参透传模式

透传模式支持以下方法： GET、PUT、POST、DELETE、PATCH、HEAD、OPTIONS

3.1. 转发客户端请求到后端服务

在透传模式下，API网关在处理签名和授权后，会将请求透明传输给后端，对于不同位置的透传规则如下

• Path: 当用户将API的请求路径配置为/path/to/[user]的格式时，可以同时配置/path/backend/[user]到后端服务路径上，API网关会识别前端路径参数并将其映射到后端服务路径上

• QueryString: 透明传输给后端，保持原始接收到的QueryString的顺序与格式

• Header: 除一些系统头和以X-Ca-开头的Header以外，网关会透传其余的Header给后端，API网关会使用ISO-8859-1编码读取和转发Header，所以如果你在Header中传递了非法的编码，可能会收到非预期的结果，对于系统以及API网关保留Header的处理逻辑，请参考“章节6.Http Header处理规则”

• Body: 包体会透明转发给后端，如果用户在API配置中设置了自定义Content-Type，则使用设置的Content-Type，否则转发客户端提供的Content-Type头

3.2. 转发后端应答给客户端

在透传模式下，如果后端成功返回应答，API网关会将来自后端服务的HTTP应答转发给客户端，如果在处理过程中失败了，由API网关生成错误码，错误处理请参考错误代码表，透传规则如下

• StatusCode: 透传来自后端应答的错误码

• Header: API网关会过滤或添加一些系统Header和名字以X-Ca-起始的保留Header，透传来自后端应答的其他Header，详细参考章节6. Http Header处理规则

• Body: API网关会将来自后端服务应答的包体转发给客户端，后端应答的Content-Type为空，则补充一个默认值：application/oct-stream

可以通过使用错误码映射插件，来改写客户端的应答码。

4. 入参映射（过滤未知参数）模式

API网关会根据用户配置的所有参数执行校验与映射，如果客户端传递了未在配置中的参数，参数将会被API网关过滤掉，不会转发给后端，如果您希望网关转发未配置参数给后端，请参考章节5。在参数映射模式下，API网关可以支持query,header,host,path,formData位置下的参数，并进行参数值的类型判断、校验，并进行向后端的映射。

4.1. 参数类型

API网关目前支持以下参数类型

Float类型与Double类型在处理标准与过程一致，不再单独列出。

4.2. 参数校验配置

• 参数校验可通过控制台、OpenAPI或导入Swagger的方式设置，设置方式与含义如下

• OpenAPI的参数配置参考：创建API->RequestParameter

• Swagger参数配置参考：通过导入Swagger创建API

参数校验的一些匹配规则：

• OpenAPi与Swagger对参数类型的取值定义不同，本节的描述参考Swagger标准

• 如果不设置参数类型，默认的类型为String

• 如果参数类型的输入格式与当前类型的支持格式不符，会报错误码： I400IP Invalid Parameter :...

• 如果参数设置为了必选，如果客户端的请求中不传递，网关会阻拦这个请求，并报错误码： I400MP Invalid Parameter Requried:...

• 可选参数可以配置缺省值，当客户端不传递这个参数时，使用配置的缺省值传递给后端，但API网关不认为空字符串： ''是合法的缺省值，网关不会将配置为空字符串的缺省值传给后端。

• 当参数处于query,formData位置时，对于形如a或a=格式的输入，如?b=1&a，API网关认为输入参数为空字符串''

  • 此时如果参数设置必选，不报错

  • 如果参数设置为可选且配置了缺省值，网关将不使用缺省值，将空串传递给后端

• 当参数类型为Integer,Long,Float,Double值时，如果输入为空字符串''，则认为此参数没有传递， 

  • 当此参数为必选时，网关会阻拦这个请求，并报错误码400: <I400MP> Invalid Parameter Requried: ...。

  • 当此参数为可选且存在缺省值配置时，使用缺省值发送给后端

• 最小长度与最大长度的判断依据为大于等于最小长度和小于等于最大长度，可以单独设置，或同时设置，只有大于0的配置才会生效

• 正则表达式的最大允许长度为40个字符，

• 字符串类型和数字类型均可以使用枚举设置，使用逗号分隔：比如江,河,湖,海，如果输入值不在列表中，会报错误码：I400IP: Invalid Parameter :...

• 如果参数类型设置为ARRAY数组类型，只有query, formData, header三个位置的参数支持数组格式，数组参数的校验规则对可以对每个数组元素生效，类型由数组参数类型字段指定，默认为字符串

4.3. 后端参数映射规则

• 用户可以设置参数的后端位置与后端名称，API网关会在发送请求给后端服务时，进行参数位置与名称的转换

• API网关的参数类型仅用于校验，不会变更传递到后端的形式，如Double类型的参数如果输入为a=1不会被更改为a=1.0，

• 参数类型为ARRAY时，后端位置只能为query,formData,header，发送给后端时使用会多个参数或多个Header的方式，如a=1&a=2, 不使用a=1,2的方式

• 传递给后端的QueryString会使用UTF-8编码的URL Encode进行重新组装

• 如果参数中包含了Form参数时，会使用application/x-www-form-urlencoded; charset=utf-8或multipart/formdata; charset=utf-8作为包体格式发送给后端 

  • 如果参数中包含File类型，会使用multipart/formdata; charset=utf-8进行组装，否则使用application/x-www-form-urlencoded; charset=utf-8进行组装

  • 如果用户在API定义的后端服务部分，设置了自定义Content-Type，则会以用户的Content-Type发给后端，如果用户自定义的Content-Type形式属于application/x-www-form-urlencoded; charset=???或multipart/formdata; charset=???形式，则使用自定义中描述的Encoding进行组装，对于其他的Content-Type，不进行编码的特殊处理

• 当转发的参数处于header位置时，网关会使用ISO8859-1编码进行转换和发送

4.4. 转发后端应答给客户端

在映射模式下，如果后端成功返回应答，API网关会将来自后端服务的HTTP应答转发给客户端，如果在处理过程中失败了，由API网关生成错误码，错误处理请参考API网关异常处理，透传规则如下

• StatusCode: 透传来自后端应答的错误码

• Header: API网关会过滤或添加一些系统Header和名字以X-Ca-起始的保留Header，透传来自后端应答的其他Header，详细参考章节6. Http Header处理规则

• Body: API网关会将来自后端服务应答的包体转发给客户端，后端应答的Content-Type为空，则补充一个默认值：application/oct-stream

可以通过使用错误码映射插件，来改写客户端的应答码。

5. 入参映射（透传未知参数）模式

入参映射（透传未知参数）模式与入参映射（过滤未知参数）模式的校验与处理机制一致，区别在于透传未知参数模式下，请求中的未知参数会在原位置上透传给后端，而过滤未知参数模式下，未知参数会被过滤掉。

6. Http Header处理规则

一般来讲，所有以X-Ca-开头的Header均为API网关保留Header, API网关会对X-Ca-的Header做特殊处理，请不要在您的业务中使用X-Ca-开头的头，否则会导致头被过滤，或产生未预期的行为。

• 所有标记为重建的Header不会透传，网关会重新添加为网关设置的值。

• 未在表中出现的Header如果客户端请求为透传模式，则将请求头透传给后端，如果为映射模式，则除默认的HttpHeader外，其余的Header会被过滤。

• 未在表中出现的应答的Header默认均透传给客户端。