MultipartReader 与 ParseMultipartForm 为什么不能混用

我第一次遇到这个问题时，报错出现在真正的上传 Handler 里：代码刚调用 r.MultipartReader()，就得到 http: multipart handled by ParseMultipartForm。奇怪的是，Handler 本身根本没有调用 ParseMultipartForm。最后沿着调用链往前找，才发现认证中间件为了读取一个字段，提前执行了 r.FormValue("token")。

先给结论：MultipartReader 与 ParseMultipartForm 不是可以前后叠加的两个步骤，而是同一个 Request.Body 的两种互斥处理模型。前者把请求体交给应用逐段消费，后者一次性聚合整个表单。谁先取得所有权，另一条路径就必须停止。

官方文档：https://pkg.go.dev/net/http#Request.MultipartReader

问题原文：明明只想取一个字段，为什么流式读取失效了

下面这段中间件看起来很自然，却悄悄改变了后续 Handler 的处理方式：

func readToken(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.FormValue("token") // 可能隐式解析整个 multipart 表单
        ctx := context.WithValue(r.Context(), tokenKey{}, token)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func upload(w http.ResponseWriter, r *http.Request) {
    mr, err := r.MultipartReader() // 此时可能返回 handled by ParseMultipartForm
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    _ = mr
}

FormValue 会在需要时调用 ParseMultipartForm，而且它会忽略解析错误。于是，真正的冲突点可能发生在 Handler 之前。类似的隐式入口还有 PostFormValue 与 FormFile。排查这类报错时，不应只搜索当前函数，还要检查中间件、鉴权器、日志组件和框架绑定逻辑。

根因不是调用顺序，而是两种所有权模型

Request.Body 是向前读取的数据流。MultipartReader 返回读取器后，应用通过 NextPart 依次取得每个 part，并决定立刻处理、丢弃还是写入目标存储。标准库不会替应用构建完整的 MultipartForm。

ParseMultipartForm 则调用 multipart reader 的 ReadForm，把文本字段和文件索引汇总到 r.MultipartForm。文件部分在内存阈值内保留，超出的部分可落到临时文件。这个模型追求的是后续随机访问和辅助方法的便利。

为了阻止两套逻辑争夺同一个请求体，net/http 在内部使用一个特殊的 multipartByReader 哨兵值。调用 MultipartReader 后，r.MultipartForm 会被标记为“已由 reader 接管”；随后再调用 ParseMultipartForm，标准库直接返回 http: multipart handled by MultipartReader。反过来，表单已经被完整解析后再要 reader，则返回 http: multipart handled by ParseMultipartForm。

所以这并不只是“请求体可能读空了”。标准库主动把所有权冲突变成可预测的错误，避免应用在半解析状态下继续运行。

图1：同一个请求体对应两种互斥的 multipart 所有权模型。

到底该选哪一个

我的选择原则很简单：如果业务真正关心“流式”，就从最外层开始保持流式，字段也在同一个 NextPart 循环里处理；如果业务更关心按字段名随机访问，就完整解析一次，不再调用 MultipartReader。

正确做法一：把整个上传边界交给 MultipartReader

下面的示例先限制整个请求体，再逐段读取。文本字段单独设置较小上限，文件内容则边读边写。示例中的 openTarget 代表你自己的安全存储逻辑，不应直接信任客户端文件名。

func streamUpload(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 1

这个 Handler 一旦调用 MultipartReader，后面就不要再调用 FormValue、PostFormValue、FormFile 或 ParseMultipartForm。字段顺序也要纳入协议设计：如果文件可能先于认证字段出现，就应把认证信息放在请求头，或者明确规定元数据 part 必须在文件 part 之前。

正确做法二：完整解析一次，再使用辅助方法

当表单规模可控、业务需要按字段名访问时，完整解析更简洁：

func parsedUpload(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 32

这里最容易误解的是 maxMemory。它主要控制文件 part 在内存中的额度，并不是整个请求体的硬上限；超出的文件内容可以转入磁盘临时文件。真正限制请求体总量，应在解析前使用 http.MaxBytesReader，并为反向代理、网关和应用层设置一致的合理上限。

最容易踩坑的是隐式解析

如果中间件需要认证信息，我更倾向于把它放在 Header、URL 查询参数或独立的元数据请求中。这样中间件不必触碰 multipart body。若认证字段必须位于 multipart 中，就应由最终上传边界统一处理，而不是让中间件和 Handler 分别选择不同模型。

另一种合理方案是：中间件明确选择 ParseMultipartForm，把已经解析出的必要值通过 Context 传给后续 Handler，并约定后续只使用聚合模型。但这时后续代码绝不能再尝试流式读取。

图2：辅助方法的隐式解析依赖与推荐的中间件边界。

常见误区

误区一：先 ParseMultipartForm，再用 MultipartReader 读大文件

不可行。完整解析已经消费并组织了 multipart 内容，标准库也会明确拒绝 reader 模式。应该一开始就决定使用哪一种模型。

误区二：Clone 一份 Request 就能读两次

r.Clone(ctx) 不会把请求体复制成两份可重放数据，克隆后的请求仍共享底层 Body。除非你主动把原始字节完整缓存并重建 reader，否则不能获得第二次读取；对大文件这么做通常也失去了流式处理的意义。

误区三：只调用了 ParseForm，不会影响 multipart

单独的 ParseForm 不会完整解析 multipart body，但 ParseMultipartForm 会先调用它，而 FormValue、PostFormValue 和 FormFile 又可能触发 multipart 解析。排查时要看最终实际走到的调用链。

误区四：maxMemory 已经限制了所有上传大小

它不是总请求体限制。整体解析模式下，超出内存额度的文件部分可进入临时文件；流式模式下则由应用负责每个 part 的读取边界。两种模式都应配合总请求体限制、字段级限制、超时和存储配额。

边界情况与排障清单

• 看到 handled by ParseMultipartForm：向前搜索 ParseMultipartForm、FormValue、PostFormValue、FormFile 以及框架的自动绑定。
• 看到 handled by MultipartReader：确认此前是否已有中间件或 Handler 调用过 MultipartReader。
• 流式上传必须按顺序处理 part；不要假设某个字段一定已在文件之前出现，除非协议明确保证。
• 整体解析要设置总请求体上限，并在使用结束后清理 MultipartForm 的临时文件。
• 不要把客户端提供的文件名直接拼接到服务器路径；文件名、MIME 类型与内容都需要独立校验。
• 如果多个组件都需要请求信息，传递已解析的明确值或业务对象，不要让每层都重新读取 Body。

延伸问题：真的需要同时拥有两种能力吗

有时需求会说：“既要流式写入，又要让后续逻辑随时读取所有表单字段。”这通常意味着接口边界需要重新设计，而不是继续叠加 API。可以把稳定元数据放入 Header，把复杂元数据拆成单独请求，或者在同一个流式循环中构建一个受限的小型字段映射，同时让文件内容继续流向目标存储。

只有在审计、签名或协议转换等特殊场景，才可能使用 io.TeeReader 或磁盘暂存重建请求体。但这会引入容量、清理、错误恢复与安全问题，不能作为普通上传的默认方案。

一句话收尾：multipart 请求体只选一个主人。需要顺序、低内存和即时处理，就从一开始使用 MultipartReader；需要便利的字段访问，就限制总量后调用 ParseMultipartForm。把这个契约放在中间件与 Handler 的公共边界上，两个经典报错自然会消失。