multipart 上传失败后怎样及时清理临时资源

Go 的 mime/multipart 适合把上传内容按 part 流式处理，但“复制失败后删文件”不能只靠一个成功分支。更稳妥的做法是：先写入同目录临时文件，所有步骤成功后再用 os.Rename 提交；在提交完成前，临时文件和句柄都由同一条清理路径负责。这样读取中断、磁盘写入失败、关闭失败和重命名失败都不会把半成品留在最终目录。

一、先把临时态和已提交态分开

上传处理最容易出问题的地方，是把目标路径当成工作文件直接写。请求中途断开时，目标文件可能已经存在，但它既不是完整文件，也无法仅凭文件名判断是否可用。可以把同一目录看成两个区域：*.uploading 是当前请求持有的临时态，正式文件名是可被下游读取的提交态。

临时文件放在最终目录旁边还有一个好处：提交时的 os.Rename 通常只改变目录项，失败时仍能在同一目录内删除；不要把临时文件写到另一个文件系统后再假设重命名一定是原子的。

二、用一次 defer 收口关闭和失败清理

清理逻辑应该绑定在“临时文件创建成功”之后，并用 committed 区分成功与失败。下面的函数只负责一个文件，函数返回时一定会关闭句柄；只要没有完成重命名，就尝试删除临时路径。

func storePart(part *multipart.Part, finalPath string) (err error) {
	// 临时文件与最终文件放在同一目录，便于提交时保持同文件系统边界。
	tmp, err := os.CreateTemp(filepath.Dir(finalPath), ".upload-*.uploading")
	if err != nil {
		return fmt.Errorf("create temp file: %w", err)
	}
	tmpPath := tmp.Name()
	committed := false
	defer func() {
		// 无论后续哪一步失败，都先关闭句柄，再删除未提交的临时文件。
		closeErr := tmp.Close()
		if !committed {
			_ = os.Remove(tmpPath)
		}
		if err == nil && closeErr != nil {
			err = fmt.Errorf("close temp file: %w", closeErr)
		}
	}()

	// io.Copy 让文件内容保持流式传输，不把整个 part 读进内存。
	if _, err = io.Copy(tmp, part); err != nil {
		return fmt.Errorf("copy multipart part: %w", err)
	}
	if err = tmp.Sync(); err != nil {
		return fmt.Errorf("sync temp file: %w", err)
	}
	if err = os.Rename(tmpPath, finalPath); err != nil {
		return fmt.Errorf("commit uploaded file: %w", err)
	}
	committed = true
	return nil
}

这里把关闭错误保留到返回值中，是因为某些文件系统的写入错误可能在 Close 时才暴露。Sync 不是所有业务都必须开启的强持久化保证，但如果上传成功就要立刻交给异步消费者，明确写入边界会更容易做取舍。

三、在读取 part 的循环里保持错误边界

请求处理器可以逐个读取 multipart.Part，遇到一个文件失败就返回错误，让本次请求的临时资源由 storePart 回收。不要在循环体里直接写一串 defer：那会把清理动作推迟到整个处理器结束，文件较多时会同时占用大量句柄。

func saveUpload(r *http.Request, dir string) error {
	// 生产环境应按业务限制校验 Content-Type、总大小和字段名。
	mediaType, params, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
	if err != nil || mediaType != "multipart/form-data" {
		return fmt.Errorf("invalid multipart content type: %w", err)
	}
	mr := multipart.NewReader(r.Body, params["boundary"])
	for {
		part, nextErr := mr.NextPart()
		if errors.Is(nextErr, io.EOF) {
			return nil
		}
		if nextErr != nil {
			return fmt.Errorf("read next part: %w", nextErr)
		}
		if part.FormName() != "file" {
			_ = part.Close()
			continue
		}
		finalPath := filepath.Join(dir, safeName(part.FileName()))
		if err := storePart(part, finalPath); err != nil {
			_ = part.Close()
			return err
		}
		// 这个 part 已交给 storePart，立即关闭读取端再继续下一个。
		if err := part.Close(); err != nil {
			return fmt.Errorf("close multipart part: %w", err)
		}
	}
}

示例中的 safeName 代表经过路径穿越和重名策略处理的文件名，不能直接信任客户端传来的 FileName。如果业务允许多个文件，还应先生成服务端 ID，再把原始名称作为元数据保存，避免两个 part 争用同一最终路径。

四、原子重命名只解决提交，不解决所有残留

重命名成功后才设置 committed = true，是为了让清理逻辑只关注临时路径。若最终文件已存在，覆盖策略要提前决定：使用唯一服务端 ID、拒绝覆盖，或先写版本目录再更新索引。不要用“文件存在”替代“上传已完成”的业务状态。

五、常见问题与边界处理

为什么不在 handler 外层统一 defer 删除？

外层只能知道请求结束，不一定知道每个 part 是否已提交；按文件封装清理函数，能把资源生命周期压缩到最小范围。

进程被强制终止时 defer 还能运行吗？

不能把进程级清理寄托在 defer 上。启动时扫描过期的 .uploading 文件，或用后台任务按修改时间清理，并保留足够长的重试窗口。

只删除临时文件就够了吗？

还要关闭 multipart.Part 和文件句柄，记录失败原因，并让监控区分复制失败、磁盘失败、提交失败与客户端主动断开。