request-validation

描述

request-validation 插件用于提前验证向上游服务转发的请求。该插件使用 JSON Schema 机制进行数据验证，可以验证请求的 body 及 header 数据。

属性

名称类型必选项默认值有效值描述
header_schemaobject否header 数据的 schema 数据结构。
body_schemaobject否body 数据的 schema 数据结构。
rejected_codeinteger否400[200,…,599]当请求被拒绝时要返回的状态码。
rejected_msgstring否当请求被拒绝时返回的信息。
request-validation - 图1注意

启用该插件时，至少需要配置 header_schema 和 body_schema 属性中的任意一个，两者也可以同时使用。

启用插件

以下示例展示了如何在指定路由上启用 request-validation 插件，并设置 body_schema 字段：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/5 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/get",
  5.     "plugins": {
  6.         "request-validation": {
  7.             "body_schema": {
  8.                 "type": "object",
  9.                 "required": ["required_payload"],
  10.                 "properties": {
  11.                     "required_payload": {"type": "string"},
  12.                     "boolean_payload": {"type": "boolean"}
  13.                 }
  14.             }
  15.             "rejected_msg": "customize reject message"
  16.         }
  17.     },
  18.     "upstream": {
  19.         "type": "roundrobin",
  20.         "nodes": {
  21.             "127.0.0.1:8080": 1
  22.         }
  23.     }
  24. }'

以下示例展示了不同验证场景下该插件的 JSON 配置：

枚举（Enum）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["enum_payload"],
  5.         "properties": {
  6.             "enum_payload": {
  7.                 "type": "string",
  8.                 "enum": ["enum_string_1", "enum_string_2"],
  9.                 "default": "enum_string_1"
  10.             }
  11.         }
  12.     }
  13. }

布尔（Boolean）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["bool_payload"],
  5.         "properties": {
  6.             "bool_payload": {
  7.                 "type": "boolean",
  8.                 "default": true
  9.             }
  10.         }
  11.     }
  12. }

数字范围（Number or Integer）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["integer_payload"],
  5.         "properties": {
  6.             "integer_payload": {
  7.                 "type": "integer",
  8.                 "minimum": 1,
  9.                 "maximum": 65535
  10.             }
  11.         }
  12.     }
  13. }

字符串长度（String）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["string_payload"],
  5.         "properties": {
  6.             "string_payload": {
  7.                 "type": "string",
  8.                 "minLength": 1,
  9.                 "maxLength": 32
  10.             }
  11.         }
  12.     }
  13. }

正则表达式（Regex）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["regex_payload"],
  5.         "properties": {
  6.             "regex_payload": {
  7.                 "type": "string",
  8.                 "minLength": 1,
  9.                 "maxLength": 32,
  10.                 "pattern": "[[^[a-zA-Z0-9_]+$]]"
  11.             }
  12.         }
  13.     }
  14. }

数组（Array）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["array_payload"],
  5.         "properties": {
  6.             "array_payload": {
  7.                 "type": "array",
  8.                 "minItems": 1,
  9.                 "items": {
  10.                     "type": "integer",
  11.                     "minimum": 200,
  12.                     "maximum": 599
  13.                 },
  14.                 "uniqueItems": true,
  15.                 "default": [200, 302]
  16.             }
  17.         }
  18.     }
  19. }

多字段组合（Combined）验证

  1. {
  2.     "body_schema": {
  3.         "type": "object",
  4.         "required": ["boolean_payload", "array_payload", "regex_payload"],
  5.         "properties": {
  6.             "boolean_payload": {
  7.                 "type": "boolean"
  8.             },
  9.             "array_payload": {
  10.                 "type": "array",
  11.                 "minItems": 1,
  12.                 "items": {
  13.                     "type": "integer",
  14.                     "minimum": 200,
  15.                     "maximum": 599
  16.                 },
  17.                 "uniqueItems": true,
  18.                 "default": [200, 302]
  19.             },
  20.             "regex_payload": {
  21.                 "type": "string",
  22.                 "minLength": 1,
  23.                 "maxLength": 32,
  24.                 "pattern": "[[^[a-zA-Z0-9_]+$]]"
  25.             }
  26.         }
  27.     }
  28. }

自定义拒绝信息

  1. {
  2.   "uri": "/get",
  3.   "plugins": {
  4.     "request-validation": {
  5.       "body_schema": {
  6.         "type": "object",
  7.         "required": ["required_payload"],
  8.         "properties": {
  9.           "required_payload": {"type": "string"},
  10.           "boolean_payload": {"type": "boolean"}
  11.         }
  12.       },
  13.       "rejected_msg": "customize reject message"
  14.     }
  15.   },
  16.   "upstream": {
  17.     "type": "roundrobin",
  18.     "nodes": {
  19.       "127.0.0.1:8080": 1
  20.     }
  21.   }
  22. }

测试插件

按上述配置启用插件后，使用 curl 命令请求该路由：

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

现在只允许符合已配置规则的有效请求到达上游服务。不符合配置的请求将被拒绝，并返回 400 或自定义状态码。

禁用插件

当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/5 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "uri": "/get",
  5.     "plugins": {
  6.     },
  7.     "upstream": {
  8.         "type": "roundrobin",
  9.         "nodes": {
  10.             "127.0.0.1:8080": 1
  11.         }
  12.     }
  13. }'