当前位置：首页 > 文章列表 > Golang > Go问答 > Go net/http Request.MultipartReader 怎样流式处理超大上传

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

来源：17golang原创 2026-10-25 16:59:11 0浏览收藏

上传接口从几 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，再决定把它写到哪里。它解决的是读取粒度，不会替你决定总请求大小、单文件大小、文件名安全或存储失败后的清理动作。

HTTP multipart 请求经由 Request.MultipartReader 分成 Part 并复制到目标流的静态结构说明图 — 图1：Request.MultipartReader 把 multipart 请求交给 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 自动提供的能力。