React / 系统课时
请求参数校验
请求参数校验
接口不能直接信任客户端传入的数据。本课将使用 express-validator 同时校验路径参数、查询参数和 JSON 请求体,并把所有失败项转换为统一的 400 响应,让路由处理函数只接收已经校验和转换过的数据。
学习目标
- 能为路径、查询和请求体参数分别声明校验规则
- 能集中收集错误并返回统一响应结构
- 能只读取通过校验的字段,避免额外字段进入业务逻辑
校验边界与处理顺序
参数校验应位于路由匹配之后、业务处理之前。路径参数用于定位资源,查询参数控制筛选或行为,请求体承载待创建或修改的数据;三类参数通过同一套校验中间件后,成功请求进入控制器,失败请求立即返回,不再执行后续业务代码。

安装与完整实现
在空目录中初始化项目并安装 Express 与校验库:
bash
npm init -y
npm install express express-validator预期结果:
text
命令退出码为 0;package.json 的 dependencies 中包含 express 和 express-validator。具体版本号与安装包数量可能不同。创建 app.js,定义通用 validate 中间件,再为下单接口声明三类参数规则:
js
const express = require('express');
const {
body,
matchedData,
param,
query,
validationResult,
} = require('express-validator');
const app = express();
app.use(express.json());
function validate(validations) {
return async (req, res, next) => {
// 显式执行全部规则,便于把校验逻辑封装成可复用中间件。
await Promise.all(validations.map((validation) => validation.run(req)));
const result = validationResult(req);
if (!result.isEmpty()) {
const errors = result.array().map(({ path, location, msg }) => ({
field: path,
location,
message: msg,
}));
return res.status(400).json({
code: 'VALIDATION_ERROR',
message: '请求参数不合法',
data: errors,
});
}
// 业务层只读取通过规则的字段,未声明字段不会进入 validated。
req.validated = matchedData(req, {
locations: ['params', 'query', 'body'],
});
return next();
};
}
app.post(
'/users/:userId/orders',
validate([
param('userId')
.isInt({ min: 1 })
.withMessage('userId 必须是正整数')
.toInt(),
query('preview')
.optional()
.isBoolean()
.withMessage('preview 必须是布尔值')
.toBoolean(),
body('productId')
.isInt({ min: 1 })
.withMessage('productId 必须是正整数')
.toInt(),
body('quantity')
.isInt({ min: 1, max: 99 })
.withMessage('quantity 必须是 1 到 99 的整数')
.toInt(),
]),
(req, res) => {
res.status(201).json({
code: 'OK',
message: '创建成功',
data: {
...req.validated,
orderId: 10001,
},
});
},
);
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
console.log(`API listening on http://localhost:${port}`);
});预期结果:
text
API listening on http://localhost:<PORT><PORT> 默认为 3000;通过环境变量 PORT 启动时,实际值会随配置变化。
验证成功与失败响应
启动服务后,分别发送一个合法请求和一个包含多项错误的请求:
bash
PORT=3000
curl -i -X POST "http://localhost:${PORT}/users/12/orders?preview=true" \
-H "Content-Type: application/json" \
-d '{"productId":8,"quantity":2,"ignored":"不会进入业务层"}'
curl -i -X POST "http://localhost:${PORT}/users/0/orders?preview=maybe" \
-H "Content-Type: application/json" \
-d '{"quantity":120}'预期输出:
text
HTTP/1.1 201 Created
{"code":"OK","message":"创建成功","data":{"userId":12,"preview":true,"productId":8,"quantity":2,"orderId":10001}}
HTTP/1.1 400 Bad Request
{"code":"VALIDATION_ERROR","message":"请求参数不合法","data":[{"field":"userId","location":"params","message":"userId 必须是正整数"},{"field":"preview","location":"query","message":"preview 必须是布尔值"},{"field":"productId","location":"body","message":"productId 必须是正整数"},{"field":"quantity","location":"body","message":"quantity 必须是 1 到 99 的整数"}]}成功响应中的数字和布尔值已经完成类型转换,额外字段 ignored 被 matchedData 丢弃。失败响应一次返回全部错误,客户端可以据此逐项提示,而不是反复提交请求。
关键边界
optional() 只表示字段可以缺省,不代表空字符串一定合法;是否接受空值应由业务规则明确决定。校验库负责输入格式和基础约束,库存检查、权限判断、唯一性校验等依赖数据库或外部状态的规则,仍应放在业务层处理。
对 JSON 请求体进行校验时,客户端必须发送 Content-Type: application/json,并且 express.json() 要注册在路由之前。生产项目还应在统一异常处理中识别 JSON 解析失败,避免把格式错误误报为服务器异常。
按自己的节奏,确认真正理解。