multipart-parser

multipart-parser 是一个快速、高效的多部分流解析器。它可以在任何 JavaScript 环境中使用（不仅限于 node.js），适用于多种场景，包括：

处理文件上传（multipart/form-data 请求）
解析 multipart/mixed 消息（电子邮件附件、API 响应等）
解析同时包含纯文本和 HTML 版本的电子邮件消息（multipart/alternative）

目标

本项目的目标是：

提供一个可在任何 JavaScript 运行环境中使用的多部分解析器
支持全系列 multipart/* 消息类型
在使用尽可能少内存的同时，保持足够快的处理速度

安装

从 npm 安装：

npm install @mjackson/multipart-parser

或从 JSR 安装：

deno add @mjackson/multipart-parser

使用方法

multipart-parser 最常见的用途是在构建 Web 服务器时处理文件上传。对于这种情况，parseMultipartRequest 函数是你的好帮手。它会自动验证请求是否为 multipart/form-data，从 Content-Type 头部提取多部分边界，解析 request.body 流中的所有字段和文件，并将每个部分作为 MultipartPart 对象 yield 给你，以便你可以将其保存到磁盘或上传到其他地方。

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

主模块（import from "@mjackson/multipart-parser"）假设你正在使用 fetch API（Request、ReadableStream 等）。Node.js 在 16.5.0 版本中通过 undici 项目添加了对这些接口的支持。

但是，如果你正在为 Node.js 构建依赖于特定 node API 的服务器，如 http.IncomingMessage、stream.Readable 和 buffer.Buffer（类似于 Express 或 http.createServer），multipart-parser 还提供了一个额外的模块，可直接与这些 API 配合使用。

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

底层 API

如果你直接处理多部分边界和不一定属于请求的多部分数据缓冲区/流，multipart-parser 提供了一些你可以直接使用的底层 API：

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

如果你更喜欢基于回调的 API，可以实例化你自己的 MultipartParser 并使用它：

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

示例

examples 目录包含了几个如何使用这个库的工作示例：

examples/bun - 在 Bun 中使用 multipart-parser
examples/cf-workers - 在 Cloudflare Worker 中使用 multipart-parser 并将文件上传存储在 R2 中
examples/deno - 在 Deno 中使用 multipart-parser
examples/node - 在 Node.js 中使用 multipart-parser

基准测试

multipart-parser 设计为尽可能高效，仅对数据流进行操作，在常见用法中从不缓冲。这种设计在处理任何大小的多部分负载时都能产生卓越的性能。在大多数基准测试中，multipart-parser 的速度与 busboy 一样快或更快。

重要提示：基准测试可能比较棘手，结果会因平台、参数和其他因素而有很大差异。因此，请谨慎看待这些结果。这个库的主要目的是在 JavaScript 运行时之间保持可移植性。为此，我们在三个主要的开源 JavaScript 运行时上运行基准测试：Node.js、Bun 和 Deno。这些基准测试仅用于表明 multipart-parser 在任何运行环境中都能快速完成工作。

在我的笔记本电脑上运行基准测试的结果：

> @mjackson/multipart-parser@0.4.2 bench:node /Users/michael/Projects/multipart-parser
> node --import tsimp/import ./bench/runner.ts

平台：Darwin (23.5.0) CPU：Apple M1 Pro 日期：2024年8月13日，下午6:47:34 Node.js v22.1.0 ┌──────────────────┬──────────────────┬──────────────────┬──────────────────┬───────────────────┐ │ (索引) │ 1个小文件 │ 1个大文件 │ 100个小文件 │ 5个大文件 │ ├──────────────────┼──────────────────┼──────────────────┼──────────────────┼───────────────────┤ │ multipart-parser │ '0.01 ms ± 0.08' │ '1.17 ms ± 0.27' │ '0.12 ms ± 0.03' │ '10.94 ms ± 0.24' │ │ busboy │ '0.03 ms ± 0.08' │ '3.00 ms ± 0.09' │ '0.21 ms ± 0.03' │ '30.10 ms ± 2.73' │ │ @fastify/busboy │ '0.02 ms ± 0.07' │ '1.19 ms ± 0.07' │ '0.38 ms ± 0.07' │ '12.15 ms ± 2.30' │ └──────────────────┴──────────────────┴──────────────────┴──────────────────┴───────────────────┘

@mjackson/multipart-parser@0.4.2 bench:bun /Users/michael/Projects/multipart-parser bun run ./bench/runner.ts

平台：Darwin (23.5.0) CPU：Apple M1 Pro 日期：2024年8月13日，下午6:49:45 Bun 1.1.21 ┌──────────────────┬────────────────┬────────────────┬─────────────────┬─────────────────┐ │ │ 1个小文件 │ 1个大文件 │ 100个小文件 │ 5个大文件 │ ├──────────────────┼────────────────┼────────────────┼─────────────────┼─────────────────┤ │ multipart-parser │ 0.01 ms ± 0.07 │ 0.95 ms ± 0.12 │ 0.13 ms ± 0.09 │ 9.13 ms ± 0.29 │ │ busboy │ 0.03 ms ± 0.10 │ 3.55 ms ± 0.10 │ 0.35 ms ± 0.17 │ 35.54 ms ± 2.57 │ │ @fastify/busboy │ 0.04 ms ± 0.10 │ 7.17 ms ± 0.10 │ 0.62 ms ± 0.13 │ 71.99 ms ± 3.01 │ └──────────────────┴────────────────┴────────────────┴─────────────────┴─────────────────┘

@mjackson/multipart-parser@0.4.2 bench:deno /Users/michael/Projects/multipart-parser deno --unstable-byonm --unstable-sloppy-imports run --allow-sys ./bench/runner.ts

平台：Darwin (23.5.0) CPU：Apple M1 Pro 日期：2024年8月13日，下午6:52:51 Deno 1.45.5 ┌──────────────────┬──────────────────┬───────────────────┬──────────────────┬────────────────────┐ │ (索引) │ 1个小文件 │ 1个大文件 │ 100个小文件 │ 5个大文件 │ ├──────────────────┼──────────────────┼───────────────────┼──────────────────┼────────────────────┤ │ multipart-parser │ "0.02 ms ± 0.18" │ "1.18 ms ± 1.07" │ "0.10 ms ± 0.43" │ "11.00 ms ± 1.18" │ │ busboy │ "0.04 ms ± 0.27" │ "3.02 ms ± 1.00" │ "0.29 ms ± 0.71" │ "30.22 ms ± 2.61" │ │ @fastify/busboy │ "0.05 ms ± 0.31" │ "12.32 ms ± 0.73" │ "0.77 ms ± 0.97" │ "125.04 ms ± 8.39" │ └──────────────────┴──────────────────┴───────────────────┴──────────────────┴────────────────────┘

我鼓励你自己运行这些基准测试。你可能会得到不同的结果！