Node.js / 系统课时
解析 JSON 请求体
解析 JSON 请求体
Express 只有在解析中间件运行后,才能把客户端 JSON 变成 req.body。本课用创建用户接口完成 express.json() 配置、字段校验和错误响应,示例适用于 Express 5.x。
学习目标
- 能用
express.json()解析application/json请求体,并理解中间件顺序。 - 能从
req.body读取字段并执行类型、长度和范围校验。 - 能区分 JSON 语法错误、请求体过大和业务字段非法三类失败。
先让中间件解析请求体
express.json() 是 Express 内置中间件。它只处理匹配 JSON 类型的请求,并在解析成功后把结果放到 req.body。Express 5.x 中,如果请求体没有被解析,req.body 默认是 undefined,因此不能假设它一定是对象。
中间件必须出现在需要读取 req.body 的路由之前。下面把单次 JSON 请求体上限明确设为 32kb;实际接口应根据业务数据量设置上限,而不是无限放大。

// 必须放在需要读取 req.body 的路由之前。
app.use(express.json({ limit: '32kb' }));这是片段示例,需放在 const app = express() 之后、读取 req.body 的路由之前。生效后,合法 JSON 会被解析为 JavaScript 值;不匹配的 Content-Type 不会由该中间件解析。
校验请求头和业务字段
请求体来自客户端,解析成功只代表 JSON 语法正确,不代表字段可信。本例要求 name 是去除首尾空格后长度为 1~50 的字符串,age 是 0~130 的整数。客户端还必须发送 Content-Type: application/json,否则返回 415 Unsupported Media Type。
只写 const { name, age } = req.body 不够稳妥,因为 req.body 可能是 undefined,也可能是数组、字符串或结构不符合预期。先判断对象形态,再读取字段,可以把解析层和业务校验层的错误分开。
完成一个可运行的 JSON 接口
若项目还没有 Express,先安装 5.x:
npm install express@5预期结果
命令以退出码 0 结束,package.json 的 dependencies 中记录 express 5.x。创建 app.js,保存后运行 node app.js:
const express = require('express');
const app = express();
// 解析器必须位于读取 req.body 的路由之前。
app.use(express.json({ limit: '32kb' }));
app.post('/users', (req, res) => {
// 解析成功不代表业务输入合法,先检查媒体类型与结构。
if (!req.is('application/json')) {
return res.status(415).json({ error: 'content type must be application/json' });
}
const body = req.body;
if (body === null || typeof body !== 'object' || Array.isArray(body)) {
return res.status(400).json({ error: 'body must be a JSON object' });
}
const name = typeof body.name === 'string' ? body.name.trim() : '';
const age = body.age;
if (name.length < 1 || name.length > 50) {
return res.status(400).json({ error: 'name must be 1-50 characters' });
}
if (!Number.isInteger(age) || age < 0 || age > 130) {
return res.status(400).json({ error: 'age must be an integer from 0 to 130' });
}
return res.status(201).json({ name, age });
});
app.use((err, req, res, next) => {
// 解析层错误与字段校验错误使用不同的响应路径。
if (err && err.type === 'entity.parse.failed') {
return res.status(400).json({ error: 'invalid json' });
}
if (err && err.type === 'entity.too.large') {
return res.status(413).json({ error: 'body too large' });
}
return next(err);
});
app.listen(3000, () => {
console.log('http://localhost:3000');
});预期输出
http://localhost:3000保持服务运行,在另一个终端发送合法请求:
curl -s -w '\nHTTP %{http_code}\n' -X POST "http://localhost:3000/users" -H "Content-Type: application/json" -d '{"name":"Ada","age":36}'预期输出
{"name":"Ada","age":36}
HTTP 201把解析错误和字段错误分开
如果 JSON 本身缺少引号、括号不配对,错误发生在 express.json() 阶段,路由不会正常拿到解析结果;本例的错误处理中间件会返回 400。如果请求体超过 32kb,则返回 413。这两类错误都应在业务处理之前结束请求。
JSON 语法正确但字段不合法属于另一层问题,例如 {"name":"","age":200} 会通过 JSON 解析,却应由路由校验返回 400。生产接口通常还会使用专门的 schema 校验库,但无论是否引入库,都应保持同一原则:先解析,再验证结构和类型,最后才执行数据库写入或其他副作用。