Go 文件上传为什么要先落临时文件：流式写入、校验和原子替换

文件上传接口最容易被忽略的风险，从来不是“能不能收到文件”，而是传输到一半时服务端会留下什么。把2GB的请求体一次性读进内存，高峰期很可能直接触发进程OOM；先写入同目录的临时文件，做完大小、哈希和格式校验后，再通过原子替换生成正式文件，就算中途出错也能顺手把未完成的半成品清理干净。

先看一个不安全的上传写法

很多入门示例会直接调用 io.ReadAll(r.Body)，然后把返回的字节切片直接交给后续逻辑。处理几MB的小头像当然没什么问题，但遇上备份包、短视频或者批量导入这类大文件，内存峰值就会变成“文件大小 + 解码、校验产生的额外副本”，很容易把服务拖垮。

body, err := io.ReadAll(r.Body)
if err != nil {
    http.Error(w, "读取上传内容失败", http.StatusBadRequest)
    return
}
if len(body) > 2

这个写法还有个更隐蔽的漏洞：写入正式路径的操作跑在校验前面。万一进程中途退出、磁盘写满或是哈希校验不匹配，data/report.bin 很可能已经生成了，却不是一份完整可用的文件。

让请求体沿着流式链路落到临时文件

整个上传链路可以拆成四个清晰的状态：请求体开始流入、数据写入临时文件、所有校验通过、替换为正式对外文件。每个状态都对应可直接检查的文件或返回值，排查问题的时候根本不用猜“文件到底写到哪一步了”。

先给请求体加上限，再创建临时文件。http.MaxBytesReader 可以在HTTP层就直接截断超过大小限制的请求，但复制循环里仍然要检查实际读取到的字节数，毕竟客户端传过来的Content-Length字段本身就不能完全信任。

const maxUpload = 2  maxUpload {
        return "", written, [32]byte{}, fmt.Errorf("upload too large")
    }
    if err := temp.Sync(); err != nil {
        return "", written, [32]byte{}, err
    }
    var sum [32]byte
    copy(sum[:], digest.Sum(nil))
    keep = true
    return tempName, written, sum, nil
}

这里的 io.MultiWriter 能让写盘和哈希计算共享同一遍数据流，不需要额外把整个临时文件从头到尾再读一遍。Sync 不是为了让接口响应速度更快，而是在正式替换之前先确认内核已经把所有数据都提交给文件系统；要不要再额外做目录同步，可以根据存储介质和业务对数据可靠性的要求自行决定。

校验通过后，为什么还要做原子替换

临时文件写完并不代表可以直接把它重命名为对外提供服务的固定文件名。更稳妥的做法是：临时文件和正式文件放在同一个文件夹里，所有校验完成之后调用 os.Rename。同一个文件系统下的重命名操作是原子的，访问者要么看到之前就存在的旧完整文件，要么看到刚替换好的新完整文件，绝对不会碰到复制到一半的中间状态。

func publishUpload(tempName, finalName string, expected [32]byte, actual [32]byte) error {
    if expected != actual {
        return fmt.Errorf("checksum mismatch")
    }
    if err := os.Rename(tempName, finalName); err != nil {
        return fmt.Errorf("replace final file: %w", err)
    }
    return nil
}

如果业务要求正式文件不能被覆盖，就不要把“文件存在即上传成功”的逻辑混在替换流程里。可以先用数据库记录上传任务的状态，再根据实际业务规则决定是直接拒绝重复文件、自动生成递增版本号，还是用全局唯一的对象名来存储。核心原则只有一个：正式存储路径永远只接收已经完整核验过的临时文件。

失败路径要把三类资源全部回收干净

上传失败的场景很常见：客户端中途断开、磁盘空间不足、文件大小超限、哈希校验不匹配、进程收到停止信号等等。每一条失败分支都要确认三件事：文件句柄已经正常关闭、临时文件已经被删除、数据库里的上传任务状态没有卡在“处理中”。

• 数据复制阶段失败：日志里保留对应请求ID，直接删除临时文件即可。
• 文件大小超限：直接返回413状态码，不要把超限文件传给后续的格式解析器。
• 哈希校验不匹配：不要执行替换正式文件的操作，日志里同时记录期望值和实际值的短摘要方便排查。
• 替换成功之后：再更新数据库的任务状态为完成，避免出现“数据库标记上传完成但对应文件还没落盘”的反向时序问题。

临时文件夹还要配一个定时清理任务。比如只清理修改时间超过24小时、文件名匹配 .upload- 的文件，同时避开当前时间范围内正在被写入的活跃文件。清理动作要记录删除数量和失败数量，绝对不能用直接清空整个文件夹的粗暴方式解决临时文件堆积问题。

用最小检查确认整个链路没有逻辑漏洞

本地测试验证的时候，可以提前准备一个符合大小限制的10MB文件，再加一个超过限制的测试文件，分别监控内存占用曲线、接口返回码、临时文件夹的文件残留情况，以及最终正式路径下的文件内容。重点不是只看接口返回200状态，而是要确认最终文件的SHA-256和客户端上传前算出来的摘要完全一致。

sha256sum ./sample.bin
curl -T ./sample.bin http://127.0.0.1:8080/upload
find ./data -maxdepth 1 -name '.upload-*' -print
ls -lh ./data/report.bin

如果正式文件在上传还没结束的时候就已经可以被下载，说明对外读的路径绕过了临时文件策略；如果上传失败后临时文件夹的文件量持续增长，说明某个返回分支漏掉了清理逻辑。把这两项作为常规回归检查，比只压测成功请求更容易提前挖到隐藏的问题。

相关问题

临时文件一定要放在正式文件同一个目录吗？

如果希望用 os.Rename 完成同文件系统内的原子替换，最好放在同一个文件夹或者同一个挂载点下。跨文件系统的重命名操作会退化成先复制全量数据再删源文件的模式，没法提供同样的原子可见性保证。

只校验Content-Length能不能限制大文件？

不能。它可以作为提前拒绝超限请求的第一层提示，但实际写入数据的时候仍然要限制读取上限、检查实际读到的总字节数，客户端主动断开或是用分块传输的场景下尤其要注意。

为什么不直接覆盖正式文件？

直接覆盖正式文件会让正在并发读取的用户拿到只写了一半的损坏内容。用临时文件做完所有校验再做原子替换，能把“后台写入数据的过程”和“面向用户开放访问”两个阶段完全隔离开。

把文件状态设计成可回收的完整生命周期

一个可靠的Go文件上传接口，不是把请求体落地存下来就完事了。它要能清晰回答几个问题：数据从哪里来、经过了哪些校验、当前落在哪个存储路径里、失败后怎么自动回收、什么时候对外部访问者可见。流式写入把内存占用控制住，哈希和大小校验确认内容完整，原子替换保护正式文件不被污染，定时清理任务负责收尾，四层逻辑配合起来，才是可以长期稳定运行的生产级上传链路。