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 后即可运行。

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

预期输出

text
Listening on http://localhost:3000

打开第二个终端发送 JSON:

bash
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/json" --data '{"name":"Lin","level":3}'

预期输出

json
{"received":{"name":"Lin","level":3}}

再发送表单数据:

bash
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/x-www-form-urlencoded" --data "name=Lin&level=3"

预期输出

json
{"received":{"name":"Lin","level":"3"}}

表单里的 level 会保持字符串 "3",这是 URLSearchParams 的正常行为;如果业务需要数字,应在字段校验阶段显式转换,而不是在通用请求体解析器里猜测类型。

用错误输入验证边界

先测试非法 JSON。服务端应拒绝解析失败的请求,而不是把原始文本继续传给业务逻辑。

bash
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: application/json" --data '{"name":}'

预期输出

json
{"error":"Invalid JSON"}

再测试不支持的媒体类型:

bash
curl -s -X POST "http://localhost:3000/echo" -H "Content-Type: text/plain" --data "hello"

预期输出

json
{"error":"Unsupported Media Type"}

生产项目还应把 1 MiB 调整为接口级限制,例如普通 JSON API 可设 256 KiB~1 MiB,文件上传则应改用流式上传或 multipart 解析,而不是把整个文件 Buffer.concat() 到内存。

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

目录与阅读设置

阅读设置

17

记录一个想法

接收请求体数据

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

登录哪都通