Go multipart.Reader失败时清理临时上传文件的资源方案

Go 使用 multipart.Reader 流式接收上传文件时，最容易遗漏的是“已经创建但还没有提交”的临时文件。可靠做法是把清理分成两层：当前 Part 写入失败，立即关闭并删除当前文件；同一次请求的后续 Part 失败，则回滚之前已经写成功的临时文件。全部部件处理完成后，才把路径交给后续业务。

官方文档：https://pkg.go.dev/mime/multipart

先划分 multipart 的临时文件责任边界

Reader 是按部件迭代的解析器，NextPart 返回 io.EOF 表示没有更多部件。它只负责从请求体中读出 Part，不知道业务要把文件保存在哪里。只要代码调用了 os.CreateTemp，这个路径就进入了业务自己的资源生命周期。

另一条路径是 ReadForm(maxMemory)：文件部件超过内存预算时，标准库会使用临时文件，返回的 Form 提供 RemoveAll 删除这些临时文件。两种模式不要混用清理假设。

把单个 Part 做成失败即删的写盘单元

关键点不是在所有分支里手写 os.Remove，而是让“函数没有返回成功路径”成为删除条件。下面的函数同时处理读取失败、写入失败、同步失败和关闭失败；代码中的中文注释只保留对资源边界有帮助的部分。

func savePart(part *multipart.Part, dir string) (path string, err error) {
	// 当前函数拥有 Part 和临时文件，成功前任何错误都必须回滚。
	defer part.Close()

	f, err := os.CreateTemp(dir, "upload-*")
	if err != nil {
		return "", fmt.Errorf("create temp file: %w", err)
	}
	path = f.Name()
	defer func() {
		// 关闭也可能失败；只要函数最终失败，就不留下半成品。
		if closeErr := f.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("close temp file: %w", closeErr)
		}
		if err != nil {
			if removeErr := os.Remove(path); removeErr != nil {
				err = fmt.Errorf("%w; remove temp file: %v", err, removeErr)
			}
			path = ""
		}
	}()

	// io.Copy 读取 Part 并写入临时文件，途中中断会触发上面的回滚。
	if _, err = io.Copy(f, part); err != nil {
		return "", fmt.Errorf("copy upload part: %w", err)
	}
	// Sync 让“写成功”不只代表数据进入用户态缓冲区。
	if err = f.Sync(); err != nil {
		return "", fmt.Errorf("sync temp file: %w", err)
	}
	return path, nil
}

这里的 path 只有在函数返回 nil 错误时才有意义。清理失败也要进入错误日志或监控，否则磁盘权限变化、目录被占用等问题会被原始读取错误掩盖。

为整次请求保留可回滚文件清单

仅清理当前文件还不够：第一个文件可能已经写完，第三个文件才发生读取错误。请求级处理器应把成功写入的路径暂存到 saved，全部部件成功后再提交；任一中途错误都删除清单中的文件。

func receiveUploads(mr *multipart.Reader, dir string) (saved []string, err error) {
	// 请求尚未提交前，saved 中的路径都属于本次事务。
	defer func() {
		if err == nil {
			return
		}
		for _, path := range saved {
			// 回滚阶段继续清理，失败项交给日志和定时任务兜底。
			if removeErr := os.Remove(path); removeErr != nil {
				log.Printf("remove rolled-back upload %q: %v", path, removeErr)
			}
		}
		saved = nil
	}()

	for {
		part, nextErr := mr.NextPart()
		if errors.Is(nextErr, io.EOF) {
			break
		}
		if nextErr != nil {
			return nil, fmt.Errorf("read next part: %w", nextErr)
		}
		if part.FileName() == "" {
			// 非文件字段要消费完，避免把解析器留在半个部件上。
			if _, err = io.Copy(io.Discard, part); err != nil {
				return nil, fmt.Errorf("read form field: %w", err)
			}
			_ = part.Close()
			continue
		}
		path, saveErr := savePart(part, dir)
		if saveErr != nil {
			return nil, saveErr
		}
		saved = append(saved, path)
	}
	return saved, nil
}

业务层拿到 saved 后才可以写数据库、移动到正式目录或投递异步任务。若后续提交失败，也应把“已提交”和“待回滚”的状态写清楚，避免把已经交给异步消费者的路径再次删除。

用错误分层和清单检查资源结果

发布前可以按四项检查：临时目录是否有写权限；单个上传和整次请求是否都有回滚；句柄是否在删除前关闭；异步处理是否只接收已经提交的路径。还要设置请求体大小上限，避免清理机制正确但磁盘先被耗尽。

常见问题

为什么只在循环里 defer os.Remove 不够？

循环中的 defer 通常要到外层函数结束才执行，无法表达“本次请求失败时统一回滚、成功时保留”的提交语义；应使用请求级清单。

ReadForm 产生的临时文件也要自己遍历删除吗？

不需要自己猜路径。使用 ReadForm 时保存返回的 Form，在不再需要它时调用 form.RemoveAll()，并单独处理返回错误。

删除失败要不要覆盖原始上传错误？

不要丢掉原始错误。可以用错误包装保留两者，同时把删除失败写入日志或指标，让运维知道磁盘清理没有完成。

临时上传文件的核心不是“最后补一个删除调用”，而是明确未提交资源、单文件回滚和请求级回滚三条边界。这样即使客户端中断或后续部件损坏，磁盘上也不会长期积累半成品。