Node.js / 系统课时

校验请求参数

校验请求参数

REST API 不应把 req.params、req.query 或 req.body 直接交给业务逻辑。本篇用 Express 5.x 建立统一边界:先检查必填、类型与范围,再把合法值转换成确定类型,并对失败请求返回稳定的 400 错误结构。

学习目标

  • 区分路径参数、查询参数与请求体参数的校验责任。
  • 为整数、字符串和范围约束设计可复用的校验步骤。
  • 用固定错误码和明细列表返回可测试的 400 响应。

先定义输入契约

假设接口为 POST /users/:id?limit=10,请求体是 {"name":"Ada"}。在写判断语句前先把契约写清楚,能避免“前端传什么就接什么”的隐式规则。

位置 字段 必填 类型 约束
Path id 是 整数 1~999999
Query limit 否 整数 1~100,缺省为 20
Body name 是 字符串 去首尾空格后长度 2~40

req.params 和 req.query 中的值本质上来自 URL 文本,不能因为内容长得像数字就假定已经是整数;请求体也要在 express.json() 解析后继续做字段级校验。

路径、查询和请求体参数进入统一校验边界的流程

用同一套规则完成校验

下面示例适用于 Node.js 18+ 与 Express 5.x,前置条件是项目依赖中已有 express@5。把代码保存为 app.cjs 即可运行;parseInteger 同时处理必填、整数转换和范围检查,路由只负责组合规则;这样新增 page、offset 等字段时不必重复写四五层条件判断。

js
const express = require('express');

const app = express();
app.use(express.json({ limit: '16kb' }));

function parseInteger(value, { name, min, max, required = true }) {
  if (value === undefined || value === null || value === '') {
    return required ? { error: `${name} is required` } : { value: undefined };
  }
  const number = Number(value);
  if (!Number.isInteger(number)) {
    return { error: `${name} must be an integer` };
  }
  if (number < min || number > max) {
    return { error: `${name} must be between ${min} and ${max}` };
  }
  return { value: number };
}

app.post('/users/:id', (req, res) => {
  const id = parseInteger(req.params.id, {
    name: 'id',
    min: 1,
    max: 999999
  });
  const limit = parseInteger(req.query.limit, {
    name: 'limit',
    min: 1,
    max: 100,
    required: false
  });
  const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
  const details = [
    id.error,
    limit.error,
    name.length < 2 || name.length > 40
      ? 'name length must be between 2 and 40'
      : undefined
  ].filter(Boolean);

  if (details.length > 0) {
    return res.status(400).json({
      error: { code: 'INVALID_ARGUMENT', details }
    });
  }

  res.status(200).json({
    id: id.value,
    limit: limit.value ?? 20,
    name
  });
});

app.use((err, req, res, next) => {
  if (err?.type === 'entity.parse.failed') {
    return res.status(400).json({
      error: { code: 'INVALID_JSON', details: ['request body is not valid JSON'] }
    });
  }
  next(err);
});

const server = app.listen(0, async () => {
  const { port } = server.address();
  const base = `http://127.0.0.1:${port}`;

  const ok = await fetch(`${base}/users/42?limit=10`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ name: 'Ada' })
  });
  console.log(ok.status, await ok.text());

  const bad = await fetch(`${base}/users/0?limit=500`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ name: 'A' })
  });
  console.log(bad.status, await bad.text());

  server.close();
});

预期输出

text
200 {"id":42,"limit":10,"name":"Ada"}
400 {"error":{"code":"INVALID_ARGUMENT","details":["id must be between 1 and 999999","limit must be between 1 and 100","name length must be between 2 and 40"]}}

这里把 URL 文本转成整数后再交给后续逻辑,因此业务层拿到的是稳定类型。重复查询参数、NaN、小数和超范围数字都会进入 400 分支,而缺省的 limit 会在通过校验后统一补成 20。

让错误响应可预测

校验失败应返回 4xx,而不是抛成 500。字段错误适合统一使用 400 Bad Request,并给机器读取的错误码;JSON 语法损坏则在 express.json() 阶段返回独立的 INVALID_JSON,不要和字段范围错误混成一类。

接口测试至少覆盖五类边界:缺失必填字段、类型错误、最小值前一位、最大值后一位、合法边界值。例如 limit=1 和 limit=100 应通过,而 limit=0、limit=101 与 limit=abc 都应得到 400。

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

目录与阅读设置

阅读设置

17

记录一个想法

校验请求参数

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

登录哪都通