为上传接口设置请求体上限并正确清理临时文件

Go 上传接口的安全基线不是只判断 FileHeader.Size，而是先用 http.MaxBytesReader 限制整个请求体，再用 ParseMultipartForm 控制文件部分在内存中的阈值，并在解析后对 r.MultipartForm.RemoveAll() 做兜底清理。最终保存文件还要使用服务端生成的随机名称，写入失败时删除半成品。

这几个动作解决的是不同问题：请求体上限阻止超大上传继续消耗带宽和磁盘，maxMemory 只决定文件部分在内存与临时磁盘之间如何分配，RemoveAll 则回收解析器创建的临时文件。三者缺一项，都可能在高并发下变成资源泄漏或磁盘占满。

Go 标准库参考：https://pkg.go.dev/net/http#MaxBytesReader、https://pkg.go.dev/net/http#Request.ParseMultipartForm、https://pkg.go.dev/mime/multipart#Form.RemoveAll

先确定上传接口要保护的三个资源边界

线上最常见的误区，是把 ParseMultipartForm(2 理解成“最多上传 2 MiB”。官方定义并不是这样：这个参数表示文件部分最多有多少内容留在内存，剩余内容会写入磁盘临时文件；它不等于整个 HTTP 请求体的上限。

请求体上限应略大于业务允许的单文件大小，因为 multipart 自身还有字段和边界开销。如果产品定义“文件最多 8 MiB”，可以把完整请求体限制设为 10 MiB，再对文件字段数量、类型和业务大小做更细的检查。

在解析 multipart 之前建立总量边界

MaxBytesReader 必须在 ParseMultipartForm 或 FormFile 读取 Body 之前包住 r.Body。超过上限后读取会返回 *http.MaxBytesError，Handler 可以稳定映射为 413，而不是把它混成普通 400。

下面是一份可直接拆进项目的完整 Handler。它把限制、临时文件回收、持久化目录、失败回滚和审计日志放在同一个资源生命周期里。

package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
    "time"
)

const (
    maxRequestBytes int64 = 10  maxRequestBytes {
            // Content-Length 已知且超限时可以提前拒绝；分块请求仍由 MaxBytesReader 兜底。
            http.Error(w, "request body too large", http.StatusRequestEntityTooLarge)
            return
        }

        r.Body = http.MaxBytesReader(w, r.Body, maxRequestBytes)
        parseErr := r.ParseMultipartForm(multipartMemory)

        if r.MultipartForm != nil {
            defer func() {
                // RemoveAll 只清理由 multipart 解析器创建的磁盘临时文件。
                if err := r.MultipartForm.RemoveAll(); err != nil {
                    log.Printf("multipart cleanup failed: %v", err)
                }
            }()
        }

        if parseErr != nil {
            var tooLarge *http.MaxBytesError
            if errors.As(parseErr, &tooLarge) {
                http.Error(w, "request body too large", http.StatusRequestEntityTooLarge)
                return
            }
            http.Error(w, "invalid multipart form", http.StatusBadRequest)
            return
        }

        src, header, err := r.FormFile("file")
        if err != nil {
            // 明确要求字段名为 file，缺失或格式错误统一返回 400。
            http.Error(w, "missing file field", http.StatusBadRequest)
            return
        }
        defer src.Close()

        dst, err := os.CreateTemp(uploadDir, "upload-*")
        if err != nil {
            http.Error(w, "cannot create destination", http.StatusInternalServerError)
            return
        }

        saved := false
        defer func() {
            // Close 可重复调用；只有完整写入并关闭后才保留目标文件。
            _ = dst.Close()
            if !saved {
                _ = os.Remove(dst.Name())
            }
        }()

        written, err := io.Copy(dst, src)
        if err != nil {
            http.Error(w, "cannot save upload", http.StatusInternalServerError)
            return
        }
        if err := dst.Sync(); err != nil {
            http.Error(w, "cannot sync upload", http.StatusInternalServerError)
            return
        }
        if err := dst.Close(); err != nil {
            http.Error(w, "cannot close upload", http.StatusInternalServerError)
            return
        }
        saved = true

        requestID := fmt.Sprintf("up-%d", time.Now().UnixNano())
        log.Printf(
            "upload saved request_id=%q stored=%q original=%q bytes=%d",
            requestID, dst.Name(), header.Filename, written,
        )

        w.Header().Set("Content-Type", "application/json; charset=utf-8")
        w.WriteHeader(http.StatusCreated)
        // 响应只返回服务端标识，不暴露本机绝对路径。
        _ = json.NewEncoder(w).Encode(map[string]any{
            "ok":         true,
            "request_id": requestID,
            "bytes":      written,
        })
    }
}

func main() {
    const uploadDir = "./data/uploads"

    // 私有目录只允许当前服务账号访问；已有目录也重新收紧权限。
    if err := os.MkdirAll(uploadDir, 0o700); err != nil {
        log.Fatal(err)
    }
    if err := os.Chmod(uploadDir, 0o700); err != nil {
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    mux.HandleFunc("/upload", uploadHandler(uploadDir))

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 3 * time.Second,  // 限制慢请求头。
        ReadTimeout:       30 * time.Second, // 给合法上传保留读取时间。
        WriteTimeout:      15 * time.Second, // 限制响应写出时间。
        IdleTimeout:       60 * time.Second, // 回收空闲 Keep-Alive 连接。
    }

    log.Printf("upload service listening on %s", srv.Addr)
    log.Fatal(srv.ListenAndServe())
}

这段代码没有用客户端原始文件名拼接路径。即使标准库在解析 multipart 文件名时会做基础处理，生产服务也不应该把它当成可信存储名。用 os.CreateTemp 生成服务端名称，可以避免同名覆盖，也减少路径字符和日志对齐问题。

把解析临时文件和最终文件分开管理

ParseMultipartForm 会解析整个 multipart 请求。文件部分在超过内存阈值后可能落到系统临时目录，并通过 FileHeader.Open 统一读取。调用 r.MultipartForm.RemoveAll() 会删除这些解析临时文件，但不会替你删除应用复制到 uploadDir 的最终文件。

因此代码里有两套清理责任：

• 解析器临时文件：只要 r.MultipartForm 非空，就在请求结束时调用 RemoveAll。
• 应用目标文件：创建后先把 saved 保持为 false，复制、同步或关闭任一步失败都删除半成品。
• 成功文件：完成 io.Copy、Sync 和 Close 后才把 saved 改为 true。

如果业务还需要病毒扫描、图片解码校验或对象存储上传，可以继续保持“先临时、后提交”的模型：文件通过全部检查后再改名或提交；失败时删除暂存对象。不要在校验完成前就把文件暴露到静态资源目录。

错误响应、目录权限和日志要一起收紧

上传接口既是资源入口，也是容易被误用的高成本接口。企业环境里通常还要补上身份认证、租户配额、并发限制和可观察性。至少应保持下面这些响应语义：

日志不要记录文件内容、Cookie、Authorization 或完整表单，也不要把服务端绝对路径回给客户端。原始文件名可以用 %q 记录，让控制字符被转义；真正对外返回的是请求标识、对象 ID 或后续下载令牌。

用正常和超限请求检查行为

准备一个小文件和一个明显超过 10 MiB 的文件，分别请求接口。这里的检查重点不是压测，而是确认成功路径返回 201、超限路径返回 413，且系统临时目录不会持续留下 multipart 文件。

# 创建一个 1 MiB 的正常样例文件。
dd if=/dev/zero of=/tmp/upload-small.bin bs=1m count=1

# 创建一个 12 MiB 的超限样例文件。
dd if=/dev/zero of=/tmp/upload-large.bin bs=1m count=12

# 正常文件应得到 HTTP 201，并返回 request_id 和 bytes。
curl -i -F 'file=@/tmp/upload-small.bin' http://127.0.0.1:8080/upload

# 超限文件应得到 HTTP 413，连接不会继续无限读取请求体。
curl -i -F 'file=@/tmp/upload-large.bin' http://127.0.0.1:8080/upload

# 实验结束后删除本地样例文件，避免把测试数据留在临时目录。
rm -f /tmp/upload-small.bin /tmp/upload-large.bin

如果接口前面还有 Nginx、Ingress 或云网关，它们也可能有请求体限制。上游限制应与 Go 服务的业务限制一致或更严格，并让错误码和提示可区分；否则客户端可能只看到上游的 413，应用日志里却完全没有请求记录。

上线前按资源生命周期逐项复查

• MaxBytesReader 是否在任何表单解析之前设置。
• 请求体上限是否包含 multipart 边界与字段开销，而不是恰好等于文件上限。
• ParseMultipartForm 的参数是否被当作内存阈值，而不是上传总量。
• 成功解析和部分解析失败时，是否都能清理已创建的 multipart 临时文件。
• 目标文件复制、同步或关闭失败时，是否删除半成品。
• 是否使用私有目录和服务端随机文件名，并阻止上传目录直接执行文件。
• 是否设置身份、租户配额、并发限制、超时、结构化日志和磁盘监控。
• 反向代理与应用层的请求体限制、超时和状态码是否协调。

把上传理解成“接收一个文件”很容易漏掉清理；把它理解成“在一次请求中申请内存、临时磁盘、目标磁盘和连接时间”，设计就会清晰很多。先封住总量，再解析；临时资源归解析器回收，最终文件归业务代码提交或回滚，这才是可以长期运行的上传接口。

相关问题

ParseMultipartForm 的 maxMemory 是文件大小限制吗？

不是。它控制文件部分有多少内容保留在内存，剩余部分可能写入临时文件。整个请求体的上限应由 MaxBytesReader 或更上游的请求体限制负责。

只调用 FormFile 还需要 RemoveAll 吗？

需要关注。FormFile 在必要时会调用 multipart 解析，文件部分可能落到磁盘。显式调用 ParseMultipartForm 能控制内存阈值，并让 Handler 在请求结束时对非空 MultipartForm 调用 RemoveAll。

为什么不能直接使用 header.Filename 保存？

客户端文件名不是可靠的唯一标识，也不适合作为服务器路径。服务端随机命名能避免同名覆盖和路径字符问题；原始名称只作为经过转义的元数据保存，并在下载时通过业务规则决定是否展示。

大文件上传也适合 ParseMultipartForm 吗？

超大文件或持续流式上传更适合使用 MultipartReader 逐个处理 part，避免先解析完整表单。无论采用哪种方式，都要保留总量限制、超时、失败回滚和目标目录权限。