multipartReader流式解析上传内容

处理上传文件时，最容易被忽略的不是“能不能读到文件”，而是读取方式是否把整个请求体复制进内存。Go 的 multipart.Reader 会把请求体当作一个可迭代的 multipart 流，程序每次拿到一个 Part，再把当前分段写入目标；因此大文件的内存占用主要由缓冲区决定，而不是由文件总大小决定。

官方资料：https://pkg.go.dev/mime/multipart

下面用一个上传接口拆开这条链路：先建立“整包读取”和“流式读取”的基线，再解析 boundary，最后补上请求大小上限、文件名处理和可复现的性能记录口径。文中的图片都是静态结构说明图，不是运行截图或压测证据。

先把性能问题说清楚：文件大不等于内存必须大

一个常见的原型写法是直接调用 io.ReadAll(r.Body)，然后再交给后续逻辑拆分。这种方式简单，但峰值内存会随着请求体大小一起增长，还可能在解析和业务复制时产生第二份或第三份临时数据。

multipart.Reader 的思路不同：底层只保留解析所需的少量数据，NextPart 返回当前分段，Part.Read 从请求流中继续读取当前分段的内容。文件分段可以直接通过 io.Copy 写入目标文件，文本字段则只在明确需要时放进一个有上限的缓冲区。

这里的“更省内存”不是一个脱离场景的固定数字。记录压测时至少保留请求大小、进程峰值内存、写入字节数、part 数量和错误类型，才能把优化结论与真实负载对应起来。

从 Content-Type 取出 boundary，再创建 Reader

multipart.NewReader 需要两个输入：请求体这个 io.Reader，以及 MIME 头中的 boundary。不要手工截取字符串，使用 mime.ParseMediaType 能正确处理参数和格式错误。

package upload

import (
    "fmt"
    "io"
    "mime"
    "mime/multipart"
    "net/http"
)

func newMultipartReader(w http.ResponseWriter, r *http.Request) (*multipart.Reader, error) {
    contentType := r.Header.Get("Content-Type")
    mediaType, params, err := mime.ParseMediaType(contentType)
    if err != nil {
        return nil, fmt.Errorf("解析 Content-Type 失败: %w", err)
    }
    // 只接受 multipart 请求，避免把普通 JSON 当成上传流解析。
    if mediaType != "multipart/form-data" {
        return nil, fmt.Errorf("不支持的媒体类型: %s", mediaType)
    }
    boundary := params["boundary"]
    if boundary == "" {
        return nil, fmt.Errorf("Content-Type 缺少 boundary")
    }
    // Reader 会按需消费请求体，不支持回退或随机定位。
    return multipart.NewReader(r.Body, boundary), nil
}

func exampleUse(w http.ResponseWriter, r *http.Request) {
    mr, err := newMultipartReader(w, r)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // 这里只展示入口；真正的字段和文件处理在后文完成。
    _, _ = mr.NextPart, io.EOF
}

官方文档把 Reader 定义为 multipart body 的 part 迭代器；它按需消费输入，不支持 seeking。这个性质决定了：一旦开始从某个 Part 读取，就应该把当前 part 消费完，或者明确放弃整个请求，而不是期待稍后回到前一个分段。

用 NextPart 区分字段和文件，避免无界 ReadAll

每个 Part 都有自己的头信息。FormName 返回表单字段名，FileName 返回文件名；文件名在标准库层面会经过 filepath.Base，但业务仍然应该生成自己的存储名，不要把客户端文件名直接当作磁盘路径。

package upload

import (
    "fmt"
    "io"
    "mime/multipart"
    "os"
    "path/filepath"
    "strings"
)

func consumeParts(mr *multipart.Reader, dstDir string) (int, int64, error) {
    partCount := 0
    var written int64
    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            // 没有更多分段，当前请求完整结束。
            return partCount, written, nil
        }
        if err != nil {
            return partCount, written, fmt.Errorf("读取 part 失败: %w", err)
        }
        partCount++

        fieldName := part.FormName()
        fileName := part.FileName()
        if fileName == "" {
            // 文本字段必须设置上限，不能对未知大小直接 ReadAll。
            value, err := io.ReadAll(io.LimitReader(part, 64

这段代码有两个刻意的边界：文本字段最多读 64 KiB，文件内容不进入内存而是通过 io.Copy 写入磁盘。生产系统还应在写入失败时删除半成品，并把文件类型、扩展名、权限和病毒扫描放到独立的业务策略中。

把请求总大小限制在 Reader 外面

流式读取解决的是“不要一次性装入内存”，并不等于“输入可以无限大”。在 Handler 入口处用 http.MaxBytesReader 包住请求体，先限制整个请求的上限，再在字段和文件层面保留更细的策略。

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    // 例如把整个 multipart 请求限制为 128 MiB，具体值按业务配额调整。
    r.Body = http.MaxBytesReader(w, r.Body, 128

外层上限和内层字段上限要同时存在：外层防止整个连接长期消耗资源，内层防止单个字段把业务缓冲区撑大。不要只依赖客户端声明的 Content-Length，实际读取仍要由服务端限制。

如何记录一次可复现的性能对比

指标驱动的对比不应该只写“流式读取更快”。建议固定同一份 multipart 请求，至少记录三组数据：

• 输入指标：请求总字节数、文件 part 数、文本字段数、单个最大文件大小。
• 资源指标：进程内存峰值、GC 次数、临时文件空间峰值、目标文件写入字节数。
• 结果指标：成功耗时、达到总大小上限的错误比例、磁盘写入失败数和解析错误数。

对比组可以保持同一个 Handler 和存储目标，只替换“整包 ReadAll”与“NextPart + io.Copy”的读取策略。每组至少使用小文件、中等文件和接近上限的文件，避免用单一尺寸推导所有结论。

ReadForm 什么时候更合适

ReadForm(maxMemory) 适合业务需要统一访问字段和文件元信息的场景。它会解析整个 multipart message，并把一部分数据放在内存，超过内存预算的文件部分可以写到临时文件；但这不是一个“无需设置上限”的替代品，仍要配合总请求大小限制和临时目录容量管理。

如果接口只接收一个大文件并立即转存，NextPart 更直接；如果接口需要校验多个字段后再决定是否接收文件，应该先明确字段上限、临时文件清理和失败回滚，再决定是否使用 ReadForm。

结论：把流式解析当作资源边界设计

multipart.Reader 的价值不只是换一个 API，而是把上传请求拆成可控制的资源边界：boundary 决定如何分段，NextPart 决定处理粒度，字段缓冲区决定内存上限，io.Copy 决定文件是否绕开大块内存，MaxBytesReader 决定整个请求的硬上限。

落地时可以按这份清单复查：

1. 是否用 mime.ParseMediaType 解析 Content-Type，而不是手工切字符串？
2. 是否限制了请求总大小，并为文本字段设置了更小的读取上限？
3. 是否用服务端生成的文件名，避免把客户端路径直接拼到磁盘？
4. 是否在文件复制失败时关闭文件并清理半成品？
5. 是否用请求大小、内存峰值、写入字节和错误类型记录对比，而不是只比较耗时？

相关问题

• multipart.Reader 可以重复读取请求体吗？不可以，它按需消费底层 Reader，不支持 seeking；需要重复使用时应在更早的边界保存明确且受限的数据。
• 为什么文件上传仍然可能占满磁盘？流式读取只降低内存压力，目标文件和临时文件仍会消耗磁盘，必须设置配额和清理策略。
• NextPart 返回 io.EOF 是错误吗？它表示没有更多 part；真正的解析或读取错误应单独记录并返回。
• ReadForm 的 maxMemory 是整个请求上限吗？不是。它是表单解析的内存预算之一，整个请求仍应使用服务端大小限制控制。