Go HTTP multipart 怎样上传大文件并控制内存

Go HTTP 接收大文件时，可以用 Request.MultipartReader 按部件读取，再把文件内容分块写入私有暂存目录，避免先把整个文件装进 bytes.Buffer 或调用 io.ReadAll。内存控制还需要请求读取限额、文件大小上限和并发准入，单独设置 ParseMultipartForm 的 maxMemory 并不能代表进程内存上限。

官方文档地址：https://pkg.go.dev/net/http。本文讨论服务端接收一个multipart/form-data文件的环节，不展开客户端发送、断点续传或对象存储协议。代码为原创教学片段，未在本机运行，也不声称有实测RSS或吞吐收益。

先规定一个文件，而不是接受任意表单

假设内部导入接口只接收一个名为file的文件部件，不接受额外字段、多个文件、空文件或Content-Transfer-Encoding。文件示例上限设为512MiB，读取请求体的上限留出1MiB封装余量；这些是演示参数，不是所有业务的建议值。

应先完成认证与资源授权，再取得上传名额，最后读取请求体。暂存目录由服务端配置，放在静态文件服务之外，并预先设置访问权限、磁盘配额与巡检清理。不能让客户端通过文件名决定服务端保存路径，也不应在错误响应里暴露暂存文件名。

本文的“上传成功”分成两个业务概念：接收函数成功只意味着取得一份暂存文件；内容审核、格式解析、持久提交与后续任务确认由上层负责。不要在刚复制完文件时就告诉调用方“导入完成”。

让 MultipartReader 成为唯一请求体入口

MultipartReader适合流式处理。它和ParseMultipartForm不是先后必须调用的两步，而是这里的两种不同选择。若前置中间件已经调用FormFile、FormValue或ParseMultipartForm，正文可能已经被解析，当前函数就无法按原计划独占这个流。

接入时要沿路检查“谁会先读取Body”，包括参数绑定、审计日志与框架表单自动解析。日志只保存必要的元信息，不缓存整个上传体。框图中的请求体、MaxBytesReader、multipart.Reader、文件部件与暂存文件，是接收函数的依赖关系，不是要把多个完整副本同时保存在内存。

最小接收函数：限额、复制与清理放在同一处

下面的包函数接收已有HTTP请求和私有目录。它不负责启动服务器，不自动创建目录，也不替代认证授权。成功返回的路径只能供服务端内部后续处理，不应直接返回给客户端。

package upload

import (
    "errors"
    "fmt"
    "io"
    "log"
    "mime"
    "net/http"
    "os"
)

const fileLimit int64 = 512  fileLimit {
        return "", n, fmt.Errorf("文件超过允许大小")
    }
    if n == 0 {
        return "", 0, fmt.Errorf("不接受空文件")
    }
    // 文件已读完，再确认没有第二个字段或第二个文件。
    _, err = mr.NextPart()
    if !errors.Is(err, io.EOF) {
        if err == nil {
            return "", n, fmt.Errorf("仅允许一个文件部件")
        }
        return "", n, fmt.Errorf("multipart未正常结束: %w", err)
    }
    if err := f.Close(); err != nil {
        return "", n, fmt.Errorf("关闭暂存件: %w", err)
    }
    kept = true // 成功后暂存件的处理与删除责任转交调用方。
    return path, n, nil
}

这段代码刻意不支持“先传几个说明字段，再传文件”的宽松表单。第一部件必须是file；复制结束后，还会继续判断multipart是否正常结束。这样，额外文件不会悄悄变成无上限的第二份内容。若业务确实需要元数据，应给字段个数、字段大小和排列方式各自定义边界，而不是无条件ReadAll每个部件。

代码拒绝传输编码，是为了避免同一接口中“线上字节”和“部件读取后字节”出现额外解释差异；NextPart对特定编码有解码处理，不能把所有部件的读取长度都不加说明地当成网络原始字节数。

MaxBytesReader限制的是应用对Body的读取；multipart结束边界之后可能还存在不被此函数消费的尾部内容。若还要求整个线上请求、代理缓冲及未消费尾部都受到一致约束，需要在入口代理和服务器层同时设置策略，不能声称这一包装器已经检查了每一个抵达网络端的字节。

64KiB复制缓冲不等于64KiB进程内存

io.CopyBuffer允许提供复制缓冲，但若源或目标提供相应快速接口，复制可能不使用这个缓冲。示例用writerOnly隐藏文件的ReaderFrom，并以LimitReader包装源，使这条复制路径使用所给缓冲；这只解释复制环节，不是为整个HTTP栈建立精确内存预算。

请求头、multipart头部、TLS、网络缓冲、日志、GC与其他业务对象仍会使用内存。文件不再整体驻留堆上，并不表示进程RSS会固定不变；落盘还会使用磁盘容量和系统缓存。业务上的资源预算应把内存、并发、临时空间和持续时间一起计算。

示例最多会把fileLimit加一个字节写入暂存件，目的是判定超限；发现超限后会删除它。若磁盘配额要求连这一个字节的探测余量也不能写入，应把额外字节改为单独读取到小缓冲，再决定拒绝。

在读取前限制并发，避免无限排队

// 在进程级共享这一组名额；不要每个请求各建一份。
var uploadSlots = make(chan struct{}, 4)

func withUploadSlot(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        select {
        case uploadSlots 

这段辅助代码与前面的包共享net/http导入。四个名额是演示值；名额已满时直接拒绝，避免每个等待请求都长期占用一组应用资源。鉴权在外层完成，真正接收函数在next对应的处理器中调用。分布式多实例还应按各实例与总体存储能力分别规划，不能把一个进程内channel理解为全局额度。

上传持续时间应由服务器及入口代理按网络条件另行配置。只限制大小不限制持续时间，慢上传仍会占据名额。这里不提供适合所有网络的统一超时秒数，也不把一个Context检查描述成能立即中断所有本地磁盘写操作。

怎样把接收结果接到业务流水线

对外HTTP状态码应由上层按照错误类别映射。示例使用%w保留底层错误，便于识别MaxBytesError等类型，但没有把所有复制错误都归为客户端超限；磁盘故障、输入中断与格式损坏需要分开记录。生产代码还可给自定义格式和单文件超限错误定义独立类型，而不要靠字符串包含来分类。

成功保留的暂存件由调用方在处理结束后删除；若进程崩溃，defer不会执行，仍需按目录权限与业务登记设计孤儿文件回收。若后续提交失败，不应通过无条件重新上传制造重复业务记录，应使用明确的业务请求标识和状态查询协议。

接入前值得保留的几种输入场景

可以将空表单、空文件、恰好到达单文件上限、超出一个字节、第二文件、错误字段名、缺少结束边界、客户端中断、磁盘写失败与并发满额列入自己的回归计划。预期分别关注是否拒绝、暂存件是否遗留、是否误触发后续任务，而不仅是HTTP状态是否为200。本文没有执行这些场景或伪造结果。

常见问题

把 ParseMultipartForm 的 maxMemory 调小就够了吗？

不够。该参数涉及表单解析时文件内容的内存与临时文件分配，并非文件大小、并发数量或进程总内存的统一限额。需要流式逐部件处理时，直接选本文的读取方式，不再混用自动表单解析。

Content-Length超过上限，可以提前拒绝吗？

可以作为提前判断，但不能替代读取时限额，因为请求长度可能未知。上层应同时处理未知长度和实际读取出错的情况，而不只看头部声明。

上传进来的文件可以马上开放下载吗？

不应由接收函数直接决定。暂存目录保持私有，内容格式与业务权限检查通过后，再按业务存储规则交付；客户端的原始文件名和Content-Type都不能单独作为可信依据。

一手资料：HTTP流式表单入口与请求限额、multipart部件读取、CopyBuffer复制行为、临时文件创建与清理责任。