Go net/http Request.MultipartReader 怎样流式处理超大上传

上传接口从几 MB 变成几百 MB 后，最先要改变的是读取方式。Request.MultipartReader 会把 multipart/form-data 请求交给调用方逐个读取 Part，文件内容可以直接复制到临时文件、对象存储或其他目标流，不必先把整份表单解析成内存结构。

官方地址：https://pkg.go.dev/net/http#Request.MultipartReader

小表单可以继续用 ParseMultipartForm 追求便利；大文件上传更适合 MultipartReader：先限制整个请求，再按 Part 分流，并对单个文件读取 max+1 字节来识别超限。

Request.MultipartReader 和一次性解析有什么区别

ParseMultipartForm 适合字段少、文件小的接口，调用后可以从 Request.MultipartForm 统一读取表单。它需要完成整份 multipart 表单的解析；当文件很大或并发上传较多时，不适合作为“文件只落盘、不进内存”的默认方案。

MultipartReader 返回 multipart.Reader，调用方通过 NextPart 取下一个 Part，再决定把它写到哪里。它解决的是读取粒度，不会替你决定总请求大小、单文件大小、文件名安全或存储失败后的清理动作。

怎样按 Part 把文件写到目标流

顺序是先调用 NextPart，再通过 FileName 区分文件和普通字段。文件不要先 ReadAll；普通字段也要设置较小的上限。

package upload

import (
    "errors"
    "fmt"
    "io"
    "net/http"
    "os"
    "path/filepath"
)

func receiveMultipart(w http.ResponseWriter, r *http.Request, dir string) error {
    const maxRequest = int64(2 * 1024 * 1024 * 1024) // 整个请求最多 2 GiB。
    const maxFile = int64(512 * 1024 * 1024)         // 单个文件最多 512 MiB。
    const maxField = int64(1 * 1024 * 1024)          // 普通字段只允许 1 MiB。

    // 先限制请求总量，避免多个 Part 合计突破输入预算。
    r.Body = http.MaxBytesReader(w, r.Body, maxRequest)
    reader, err := r.MultipartReader()
    if err != nil {
        return fmt.Errorf("读取 multipart 请求失败: %w", err)
    }
    for {
        part, err := reader.NextPart()
        if errors.Is(err, io.EOF) {
            // 没有更多 Part，EOF 是正常结束。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取下一个 Part 失败: %w", err)
        }
        filename := filepath.Base(part.FileName())
        if filename == "." || filename == "" {
            // 普通字段也要限长，不能无上限地读入内存。
            value, err := io.ReadAll(io.LimitReader(part, maxField+1))
            if err != nil {
                return fmt.Errorf("读取字段 %q 失败: %w", part.FormName(), err)
            }
            if int64(len(value)) > maxField {
                return fmt.Errorf("字段 %q 超过大小限制", part.FormName())
            }
            continue
        }
        dst, err := os.CreateTemp(dir, "upload-*")
        if err != nil {
            return fmt.Errorf("创建临时文件失败: %w", err)
        }
        // 多读 1 字节，区分刚好达到上限和已经超过上限。
        copied, copyErr := io.Copy(dst, io.LimitReader(part, maxFile+1))
        closeErr := dst.Close()
        if copyErr != nil {
            _ = os.Remove(dst.Name()) // 写入失败时删除不完整文件。
            return fmt.Errorf("保存文件 %q 失败: %w", filename, copyErr)
        }
        if closeErr != nil {
            _ = os.Remove(dst.Name()) // 关闭失败同样不能留下不可用文件。
            return fmt.Errorf("关闭文件 %q 失败: %w", filename, closeErr)
        }
        if copied > maxFile {
            _ = os.Remove(dst.Name()) // 超限文件不进入后续持久化流程。
            return fmt.Errorf("文件 %q 超过大小限制", filename)
        }
        // 这里可以把 dst.Name() 交给对象存储上传队列或业务记录。
        _ = dst.Name()
    }
}

示例把 Part 直接交给 io.Copy，内存中只保留复制缓冲，而不是整份文件。真实项目还应决定临时文件生命周期、对象存储失败重试和数据库记录时机；这些属于存储策略，不是 MultipartReader 自动提供的能力。

怎样同时限制请求和单个文件

MaxBytesReader 约束整个 HTTP 请求，防止多个文件和字段相加后超预算；io.LimitReader 约束当前 Part，防止单个文件占满磁盘或绕过业务额度。

判断单文件超限时不要只把读取上限设成 maxFile，否则“恰好读满”与“后面还有内容”无法区分。设成 maxFile+1 后，如果复制字节数大于 maxFile，就删除临时文件并拒绝当前上传。

EOF、坏格式和清理错误怎么分开

NextPart 返回 io.EOF 表示所有 Part 已经消费完，应作为成功结束；其他读取错误说明请求可能截断、边界格式不完整或底层请求体读取失败。不要把所有错误都当成“没有更多文件”，否则服务器可能留下半截文件。

• 请求类型错误：MultipartReader 无法从非 multipart 请求创建读取器，应返回明确的 4xx。
• Part 读取错误：在 NextPart 或 io.Copy 处保留原始错误，区分截断与存储失败。
• 超限：删除临时文件后再返回，不要让不完整文件进入后续队列。
• 文件名：写入本地路径前使用 filepath.Base，不要直接拼接客户端路径。

小型表单使用 ParseMultipartForm 更省代码；大文件、低内存和边读边存场景使用 MultipartReader 更符合边界。选型的核心是是否需要在拿到完整表单前就开始消费文件流。

常见问题

MultipartReader 能不能让文件完全不落盘？

可以把 Part 复制到对象存储、管道或其他实现了 io.Writer 的目标；示例使用临时文件只是为了展示失败清理和大小限制。

为什么不直接用 FormFile？

FormFile 会触发 multipart 表单解析，适合便利地取单个文件。要按流处理超大上传，直接使用 MultipartReader 更容易把请求上限、Part 上限和目标写入放在同一个控制点。