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 解析失败,避免把格式错误误报为服务器异常。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

请求参数校验

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通