Skip to main content
Version: 2.15

request-validation

描述#

request-validation 插件用于提前验证请求向上游转发请求,可以验证请求的 bodyheader 数据。

该插件使用 Json Schema 进行数据验证,有关 Json Schema 的更多信息,请参阅 JSON schema

属性#

注意,header_schemabody_schema 至少填写其中一个

NameTypeRequirementDefaultValidDescription
header_schemaobject可选header 数据的 schema 数据结构
body_schemaobject可选body 数据的 schema 数据结构
rejected_codeinteger可选400[200,...,599]自定义拒绝状态码
rejected_msgstring可选自定义拒绝信息

如何启用#

创建一条路由并在该路由上启用 request-validation 插件:

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
"request-validation": {
"body_schema": {
"type": "object",
"required": ["required_payload"],
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
}
}
"rejected_msg": "customize reject message"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

测试插件#

curl --header "Content-Type: application/json" \
--request POST \
--data '{"boolean-payload":true,"required_payload":"hello"}' \
http://127.0.0.1:9080/get

如果 Schema 验证失败,将返回 400 状态码与相应的拒绝信息。

禁用插件#

在路由 plugins 配置块中删除 request-validation 配置,即可禁用该插件。

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

示例#

枚举(Enums)验证:

{
"body_schema": {
"type": "object",
"required": ["enum_payload"],
"properties": {
"enum_payload": {
"type": "string",
"enum": ["enum_string_1", "enum_string_2"],
"default": "enum_string_1"
}
}
}
}

布尔(Boolean)验证:

{
"body_schema": {
"type": "object",
"required": ["bool_payload"],
"properties": {
"bool_payload": {
"type": "boolean",
"default": true
}
}
}
}

数字范围(Number or Integer)验证:

{
"body_schema": {
"type": "object",
"required": ["integer_payload"],
"properties": {
"integer_payload": {
"type": "integer",
"minimum": 1,
"maximum": 65535
}
}
}
}

字符串长度(String)验证:

{
"body_schema": {
"type": "object",
"required": ["string_payload"],
"properties": {
"string_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
}
}
}

正则表达式(Regex)验证:

{
"body_schema": {
"type": "object",
"required": ["regex_payload"],
"properties": {
"regex_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"pattern": "[[^[a-zA-Z0-9_]+$]]"
}
}
}
}

数组(Array)验证:

{
"body_schema": {
"type": "object",
"required": ["array_payload"],
"properties": {
"array_payload": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 200,
"maximum": 599
},
"uniqueItems": true,
"default": [200, 302]
}
}
}
}

多字段组合(Multiple Fields)验证:

{
"body_schema": {
"type": "object",
"required": ["boolean_payload", "array_payload", "regex_payload"],
"properties": {
"boolean_payload": {
"type": "boolean"
},
"array_payload": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 200,
"maximum": 599
},
"uniqueItems": true,
"default": [200, 302]
},
"regex_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"pattern": "[[^[a-zA-Z0-9_]+$]]"
}
}
}
}

自定义拒绝信息:

{
"uri": "/get",
"plugins": {
"request-validation": {
"body_schema": {
"type": "object",
"required": ["required_payload"],
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
}
},
"rejected_msg": "customize reject message"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}