Node.js / 系统课时
接收请求体数据
接收请求体数据
Node.js 原生 HTTP 服务不会自动把请求体变成对象;req 本身是可读流。要可靠接收 JSON 或表单,需要按块读取、限制总字节数,再根据 Content-Type 解码。本篇会得到一个可直接运行的请求体解析器,并能正确返回 400、413 和 415。
学习目标
- 监听
http.IncomingMessage的data与end事件,分块读取请求体并正确合并Buffer。 - 为请求体设置 1 MiB 上限,避免无界占用内存。
- 根据
Content-Type解析 JSON 与application/x-www-form-urlencoded,并区分常见错误状态码。
请求体是流,不是一次性字符串
http.createServer() 回调中的 req 是 http.IncomingMessage,它继承自可读流。一次请求可能被拆成多个 Buffer 到达,块大小由网络和流内部状态决定,不能假设一次 data 就是完整 JSON。可靠做法是先累计字节数,再合并为完整缓冲区。

例如客户端发送 180 KB JSON 时,服务端可能收到 3 个、8 个甚至更多块;业务逻辑只能在流结束后把完整内容交给 JSON.parse()。空请求体也要单独处理,否则空字符串传给 JSON.parse() 会直接抛出语法错误。
先限制字节数,再决定怎样解析
下面的实现把上限固定为 1024 * 1024 字节,也就是 1 MiB。计数必须针对 Buffer.length,而不是字符串字符数,因为 UTF-8 中文通常占多个字节。超过上限时返回 413;媒体类型不支持时返回 415;JSON 语法错误返回 400。
| 情况 | 处理结果 |
|---|---|
application/json |
以 UTF-8 解码后调用 JSON.parse() |
application/x-www-form-urlencoded |
用 URLSearchParams 解析,再转成普通对象 |
| 空请求体 | 返回 null |
| 超过 1 MiB | 413 Payload Too Large |
| JSON 格式错误 | 400 Bad Request |
| 其他媒体类型 | 415 Unsupported Media Type |
Content-Type 常带参数,例如 application/json; charset=utf-8。匹配前先按分号取第一段并转为小写,避免把合法 JSON 错判为不支持的类型。
完整实现 JSON 与表单解析
下面示例只使用 Node.js 内置模块,适用于现代 Node.js 版本,使用 CommonJS、node:http、Buffer 与全局 URLSearchParams。保存为 server.js 后即可运行。
const http = require('node:http');
const MAX_BODY_BYTES = 1024 * 1024;
class HttpError extends Error {
constructor(statusCode, message) {
super(message);
this.statusCode = statusCode;
}
}
function readBody(req, maxBytes = MAX_BODY_BYTES) {
return new Promise((resolve, reject) => {
const chunks = [];
let totalBytes = 0;
let finished = false;
function fail(error) {
if (finished) return;
finished = true;
chunks.length = 0;
reject(error);
}
req.on('data', (chunk) => {
if (finished) return;
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
totalBytes += buffer.length;
// 超限后停止缓存;data 监听仍会把后续数据排空,避免继续占用内存。
if (totalBytes > maxBytes) {
fail(new HttpError(413, 'Payload Too Large'));
return;
}
chunks.push(buffer);
});
req.on('end', () => {
if (finished) return;
finished = true;
resolve(Buffer.concat(chunks, totalBytes));
});
req.on('aborted', () => fail(new HttpError(400, 'Request Aborted')));
req.on('error', fail);
});
}
async function parseBody(req) {
// 先得到完整请求体,再按媒体类型选择解码方式。
const buffer = await readBody(req);
if (buffer.length === 0) {
return null;
}
const mediaType = (req.headers['content-type'] ?? '')
.split(';', 1)[0]
.trim()
.toLowerCase();
const text = buffer.toString('utf8');
if (mediaType === 'application/json') {
try {
return JSON.parse(text);
} catch {
throw new HttpError(400, 'Invalid JSON');
}
}
if (mediaType === 'application/x-www-form-urlencoded') {
return Object.fromEntries(new URLSearchParams(text));
}
throw new HttpError(415, 'Unsupported Media Type');
}
function sendJson(res, statusCode, payload) {
// Content-Length 必须按字节计算,不能直接使用字符串长度。
const body = JSON.stringify(payload);
res.writeHead(statusCode, {
'Content-Type': 'application/json; charset=utf-8',
'Content-Length': Buffer.byteLength(body),
});
res.end(body);
}
const server = http.createServer(async (req, res) => {
// 示例只暴露 POST /echo,其他请求统一返回 404。
if (req.method !== 'POST' || req.url !== '/echo') {
sendJson(res, 404, { error: 'Not Found' });
return;
}
try {
const body = await parseBody(req);
sendJson(res, 200, { received: body });
} catch (error) {
const statusCode = error instanceof HttpError ? error.statusCode : 500;
const message = error instanceof Error ? error.message : 'Internal Server Error';
sendJson(res, statusCode, { error: message });
}
});
server.listen(3000, () => {
console.log('Listening on http://localhost:3000');
});预期输出
Listening on http://localhost:3000打开第二个终端发送 JSON:
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/json" --data '{"name":"Lin","level":3}'预期输出
{"received":{"name":"Lin","level":3}}再发送表单数据:
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/x-www-form-urlencoded" --data "name=Lin&level=3"预期输出
{"received":{"name":"Lin","level":"3"}}表单里的 level 会保持字符串 "3",这是 URLSearchParams 的正常行为;如果业务需要数字,应在字段校验阶段显式转换,而不是在通用请求体解析器里猜测类型。
用错误输入验证边界
先测试非法 JSON。服务端应拒绝解析失败的请求,而不是把原始文本继续传给业务逻辑。
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/json" --data '{"name":}'预期输出
{"error":"Invalid JSON"}再测试不支持的媒体类型:
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: text/plain" --data "hello"预期输出
{"error":"Unsupported Media Type"}生产项目还应把 1 MiB 调整为接口级限制,例如普通 JSON API 可设 256 KiB~1 MiB,文件上传则应改用流式上传或 multipart 解析,而不是把整个文件 Buffer.concat() 到内存。