Go multipart.Reader 流式接收大文件：边界解析、临时文件与失败清理

上传接口最容易被忽略的不是把文件保存下来，而是请求还没读完、磁盘写失败或客户端中途断开时，临时文件到底怎么收尾。Go 的 multipart.Reader 可以按表单边界逐段读取，配合大小限制和一次性临时文件，就能把内存占用控制在缓冲区范围内。

一个可控的上传配方：请求体、part 和临时文件

这个例子只完成一个任务：接收名为 file 的 multipart 文件，写入系统临时目录，再移动到上传目录。示例没有把文件内容放进 []byte，所以文件大小主要受磁盘和显式上限约束。

package main

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

const maxUpload = 512  maxUpload+1

这里有三个容易混淆的上限。MaxBytesReader 限制整个请求体，io.LimitReader 防止单个文件 part 超出预算，而 multipart.Reader 负责识别边界。三者不是重复配置：表单里如果还有字段，文件上限和请求总上限就应该留出差额。

为什么不能直接用原文件名覆盖目标文件

上传过程中直接打开最终路径，会让半个文件变成可见结果；进程崩溃、客户端断线和磁盘空间不足都可能留下一个看似成功的文件。临时文件写完后再同目录改名，至少能把“未完成内容”和“最终内容”分开。

filepath.Base 只处理路径层级，仍应根据业务规则限制扩展名、生成服务端文件名，并在真实应用里做内容类型和病毒扫描。这个示例保留原名只是为了让流程容易观察。

失败清理要覆盖哪些分支

上面的 committed 是一个很小但关键的状态位：只有 os.Rename 成功后才置为 true。此前任意返回路径都会触发清理临时文件。特别是 io.Copy 返回错误时，不要只记录日志后继续返回成功响应。

建议至少做三次验收：正常上传后目标文件大小与客户端一致；发送超过上限的请求后返回 413；模拟目标目录不可写或中途断开后，uploads 下没有残留的 .upload-* 文件。检查临时文件比只看 HTTP 状态更可靠。

把配方放进真实服务前的边界调整

• 文件大小：同时设置请求总量和单文件上限，并为普通字段预留空间。
• 文件名：不要把客户端文件名直接当作权限、路径或唯一性依据。
• 超时：给服务端配置读超时，避免慢速客户端长期占用连接。
• 提交：目标文件已存在时明确覆盖、拒绝或生成新名字，不要依赖平台差异。
• 恢复：如果改名成功但响应发送失败，重试请求必须有业务幂等策略。

相关问答

multipart.Reader 会把整个文件读进内存吗？

不会。它按边界读取 part，真正占用多少内存取决于你的读取缓冲和下游处理方式；如果调用会一次性返回全部内容的接口，才会重新引入内存峰值。

为什么还要保留 io.LimitReader？

请求总上限不能表达单个文件的业务预算。保留单 part 上限，可以防止表单中某个文件吃掉全部配额，并让超限行为更靠近文件处理点。

临时文件一定要放在目标目录吗？

如果最终动作是同一文件系统内的改名，放在目标目录通常更容易获得原子替换语义。跨文件系统移动可能退化成复制加删除，提交窗口也会变长。

验收清单

启动服务后，用一个小文件验证正常路径，再用超过 512 MiB 的测试流验证 413；随后检查最终目录只出现提交完成的文件。最后故意让磁盘写入失败，确认日志里有原因、HTTP 响应不是成功码，并确认临时前缀文件已经消失。这个顺序能把读取、限制、提交和清理四件事分别验明白。