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;实际接口应根据业务数据量设置上限,而不是无限放大。

JSON 请求从原始字节到业务校验的处理流程

js
// 必须放在需要读取 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:

bash
npm install express@5

预期结果

text
命令以退出码 0 结束,package.json 的 dependencies 中记录 express 5.x。

创建 app.js,保存后运行 node app.js:

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');
});

预期输出

text
http://localhost:3000

保持服务运行,在另一个终端发送合法请求:

bash
curl -s -w '\nHTTP %{http_code}\n' -X POST "http://localhost:3000/users" -H "Content-Type: application/json" -d '{"name":"Ada","age":36}'

预期输出

text
{"name":"Ada","age":36}
HTTP 201

把解析错误和字段错误分开

如果 JSON 本身缺少引号、括号不配对,错误发生在 express.json() 阶段,路由不会正常拿到解析结果;本例的错误处理中间件会返回 400。如果请求体超过 32kb,则返回 413。这两类错误都应在业务处理之前结束请求。

JSON 语法正确但字段不合法属于另一层问题,例如 {"name":"","age":200} 会通过 JSON 解析,却应由路由校验返回 400。生产接口通常还会使用专门的 schema 校验库,但无论是否引入库,都应保持同一原则:先解析,再验证结构和类型,最后才执行数据库写入或其他副作用。

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

目录与阅读设置

阅读设置

17

记录一个想法

解析 JSON 请求体

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

登录哪都通