说明 此文档仅适用于VPC实例(包含共享实例和专享实例),目前尚不适用于经典网络实例。

1. 概述

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

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

  • 透传模式: 透传模式下,API网关除Path位置的请求参数外,不对其他位置的请求参数进行映射与校验,用户参数会透明传递给后端,详细请阅读章节2. 透传模式
  • 映射模式: 映射模式下,API网关会根据用户配置的所有参数执行校验与映射,如果客户端传递了未在配置中的参数,参数将会被API网关过滤掉,不会转发给后端,详细请参考章节3. 映射模式
  • 透明映射模式: 类似映射模式,但在透明映射模式下,如果用户传递了未配置的参数,参数会被透明转发给后端,详细请参考章节4. 透明映射模式

2. 参数位置与读取规则

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

2.1. path参数

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

请求路径配置 输入 参数提取结果
/request/to/[path] /request/to/user1 path=user1
/[path1]/[path2]. /group1/user1 path1=group1, path2=user1
/[root]/* /root/user1 root=request
/[root] /root/user1 无法匹配.

- 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均被认为是值等于空字符串''的合法值,如:

QueryString输入 参数提取结果
?a=1&b=2 a: "1", b: "2"
?a=1&a=2 a: ["1", "2"] ; 参数为非array类型时仅使用第一个值
?a a: ""
?a= a: ""
?=a&b=1 b: "1" ; =a这个输入会被API网关忽略
  • *API网关对于不符合RFC3986的非法输入,直接返回错误码:I400PH: Invalid Request Path
  • *API网关支持的最大RequestUri长度为128KBytes, 超过这个限制时会返回错误码:I413RL: Request Url too Large

2.3. formData参数

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

Content-Typemultipart/formdata时,网关支持进行文件类型参数,详见章节3.4. 文件类型参数

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参数,具体例子如下

泛域名模板配置 请求Host 参数提取结果
${User}.api.io 123.api.io User: "123"
${User}.${Group}.api.io 123.g01.api.io User: "123" Group: "g01"
${Admin}.admin.api.io${User}.${Group}.api.io. 123.api.io User: "123"
${Admin}.admin.api.io${User}.${Group}.api.io 123.admin.api.io Admin: "123"
${Admin}.admin.api.io${User}.${Group}.api.io 123.u00.api.io User: "123"GroupId: "u00"
${User}.${Group}.api.io${Admin}.admin.api.io 123.admin.api.io User: "123"Group: "admin"

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

3. 参数透传模式

透传模式支持以下方法: GETPUTPOSTDELETEPATCHHEADOPTIONS

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的处理逻辑,请参考`章节5. Http头处理规则'
  • Body: 包体会透明转发给后端,如果用户在API配置中设置了自定义Content-Type,则使用设置的Content-Type,否则转发客户端提供的Content-Type

3.2. 转发后端应答客户端

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

  • StatusCode: 透传来自后端应答的错误码
  • Header: API网关会过滤或添加一些系统Header和名字以X-Ca-起始的保留Header,透传来自后端应答的其他Header,详细参考章节5. Header转发规则
  • Body: API网关会将来自后端服务应答的包体转发给客户端, 后端应答的Content-Type为空,则补充一个默认值: application/oct-stream

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

4. 参数映射模式

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

4.1. 参数类型

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

类型 类型说明 格式支持 可选校验方式
String 字符串 不限 最小长度、最大长度、枚举值、正则
Integer 32位整数 1, -1, 100 最小值,最大值,枚举值
Long 64位整数 -1233, 1001 最小值,最大值,枚举值
Double 浮点数 100,0.1,9E-9,1.01E16 最小值,最大值
Boolean 布尔值 true, false; (忽略大小写)
File 文件类型 仅用于multipart/form-data 最小长度、最大长度
Array 数组类型 参考数组字段类型 数组字段类型上的校验

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

4.2. 参数校验配置

  • 参数校验可通过控制台OpenAPI导入Swagger的方式设置, 设置方式与含义如下
名称 说明 OpenAPI的字段 Swagger中的字段
参数名 必选, API内唯一 ApiParameterName name
参数位置 必选 Location location
参数类型 可选,默认类型为String ParameterType type
数组参数类型 可选,参数类型为Array时, 指定数组字段类型 ArrayItemsType items.type
是否必填 可选, 默认为 Required required
默认值 可选, 空字符串''不是有效的默认值. DefaultValue default
最大值 可选, 输入值必须小于等于最大值 MaxValue maximum
最小值 可选, 输入值必须大于等于最小值 MinValue minimum
最大长度 可选, 仅对String类型有效 MaxLength maxLength
最小长度 可选, 仅对String类型有效 MinLength minLength
正则表达式 可选, 仅对String类型有效 RegularExpression pattern
枚举值 可选 EnumValue enum

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

  • OpenAPi与Swagger对参数类型的取值定义不同,本节的描述参考Swagger标准
  • 如果不设置参数类型,默认的类型为String
  • 如果参数类型的输入格式与当前类型的支持格式不符,会报错误码: I400IP Invalid Parameter :...``
  • 如果参数设置为了必选,如果客户端的请求中不传递,网关会阻拦这个请求,并报错误码: I400MP Invalid Parameter Requried:...``
  • 可选参数可以配置缺省值,当客户端不传递这个参数时,使用配置的缺省值传递给后端,但API网关不认为空字符串: ''是合法的缺省值,网关不会将配置为空字符串的缺省值传给后端。
  • 当参数处于query,formData位置时,对于形如aa=格式的输入,如?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-8multipart/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,详细参考5. Header转发规则
  • Body: API网关会将来自后端服务应答的包体转发给客户端, 后端应答的Content-Type为空,则补充一个默认值: application/oct-stream

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

5. 透传映射模式

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

6. 严格映射模式

严格映射参数映射模式的校验与处理机制一致,区别在于严格映射模式下,当请求中包含未知参数时会直接按报错处理。

7. Http Header处理规则

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

HeaderName 请求处理方式 应答处理方式
Connection 重建 重建
Keep-Alive 重建 重建
Proxy-Authenticate 重建 重建
Proxy-Authorization 重建 重建
Trailer 重建 重建
TE 重建 重建
Transfer-Encoding 重建 重建
Upgrade 重建 重建
Host 重建
Authorization 校验、映射或透传
Date 透传或添加默认
Content-Type 映射或透传 透传或添加默认
Content-Length 映射或透传
Content-MD5 校验并透传
Via 添加网关记录
X-Forwarded-For 在右侧添加客户端IP
X-Forwarded-Proto 添加客户端请求协议: 'http',https','ws','wss'
User-Agent 透传或添加网关UserAgent
Server 透传或添加默认
  • 所有标记为重建的Header不会透传,网关会重新添加为网关设置的值。
  • 未在表中出现的Header如果客户端请求为透传模式,则将请求头透传给后端,如果为映射模式,则除默认的HttpHeader外,其余的Header会被过滤。
  • 未在表重出现的应答的Header默认均透传给客户端。