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 等字段时不必重复写四五层条件判断。
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();
});预期输出
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。