Go os.File写入临时文件后原子替换的持久化方案

Go 服务更新配置、游标或本地状态时，直接对正式文件执行 os.File.Write，进程被终止或磁盘写入失败就可能留下半截内容。更稳妥的做法是：在正式文件所在目录创建临时文件，完整写入并检查字节数，调用 File.Sync，再关闭临时文件，最后用 os.Rename 替换正式路径。这样读者通常只会看到旧版本或完整的新版本；但“原子替换”不等于跨平台一致，也不自动等于完整的断电事务。

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

先把临时文件放到正式文件同一目录

os.CreateTemp 如果传入空目录，可能把文件建在系统临时目录。之后再移动到目标目录，既可能遇到跨文件系统错误，也不能把一次移动当成同目录原子替换。因此先用 filepath.Dir 取得目标目录，并给临时文件一个容易识别的前缀。临时文件名由系统生成，不要自己拼接固定名称，否则并发写入会互相覆盖。

写完数据后显式调用 File.Sync

Write 返回成功，只能说明这次写调用接受了数据。需要把“写入完成”和“数据已提交到稳定存储”分开处理：先检查 n 与数据长度，再调用 Sync。如果 Sync 失败，正式文件仍然不应被替换。下面的函数只展示文件更新本身，不把数据库事务、锁服务或配置框架混进来。

package atomicfile

import (
    "io"
    "os"
    "path/filepath"
)

// AtomicWrite 先准备完整临时文件，再替换正式路径。
func AtomicWrite(path string, data []byte, perm os.FileMode) (err error) {
    dir := filepath.Dir(path)
    tmp, err := os.CreateTemp(dir, "."+filepath.Base(path)+".tmp-*")
    if err != nil {
        return err
    }
    tmpName := tmp.Name()
    // 任意中途失败都删除未发布的临时文件。
    defer func() {
        if err != nil {
            _ = os.Remove(tmpName)
        }
    }()

    if err = tmp.Chmod(perm); err != nil {
        _ = tmp.Close()
        return err
    }
    n, writeErr := tmp.Write(data)
    if writeErr != nil {
        _ = tmp.Close()
        return writeErr
    }
    if n != len(data) {
        _ = tmp.Close()
        return io.ErrShortWrite
    }
    // Sync 失败时不替换正式文件，避免发布未稳定的数据。
    if err = tmp.Sync(); err != nil {
        _ = tmp.Close()
        return err
    }
    // Close 的错误也要保留，不能被后面的 Rename 覆盖。
    if err = tmp.Close(); err != nil {
        return err
    }
    // 同一目录内替换正式路径；目标存在时通常会被替换。
    return os.Rename(tmpName, path)
}

这里把清理逻辑放在 defer 中，但只在返回错误时删除临时文件。函数成功返回后，临时路径已经被 Rename 消费，不会误删正式文件。

关闭临时文件后执行 os.Rename

关闭顺序很重要：Sync 负责把当前文件内容提交到稳定存储，Close 负责结束文件句柄的使用，Rename 才负责把正式路径切换到新文件。Go 官方文档说明，os.Rename 在目标已存在且不是目录时会替换目标，但跨目录有操作系统限制；即使同目录，在非 Unix 平台也不保证原子性。

所以这段方案的“原子”要带条件理解：在支持同目录原子 rename 的系统上，它避免读者读取到正在增长的文件；如果应用必须同时支持 Windows，就要把替换失败当成正常错误路径处理，并根据目标文件系统选择平台实现。

用错误处理与检查清单收住边界

上线前可以按下面的清单检查。若目标是“读者不看到半文件”，重点是同目录临时文件和最后替换；若目标是“断电后一定能恢复新文件”，还要核对操作系统、文件系统以及目录项持久化策略，不能只增加一次 Sync 就宣称完成。

还要注意并发发布：多个 goroutine 可以安全调用同一个 os.File 的方法，但这不代表多个发布者会自动按业务顺序替换同一个目标。需要单写者、版本号或外部锁时，应在函数外层解决竞态；本文的函数只保证一次调用内部的写入顺序。

相关问题

为什么临时文件不能放在系统临时目录？

因为目标目录可能属于另一文件系统，移动会失败或失去同目录替换语义。把临时文件放到目标目录最简单可靠。

只调用 Close，不调用 Sync 可以吗？

可以完成普通写文件，但不能把 Close 当作显式稳定存储确认。需要更强的持久化语义时，应检查 Sync 返回值。

Rename 成功后是否代表断电一定保留新文件？

不一定。它主要切换目录中的名字；严格断电语义还要评估目录元数据是否持久化，以及目标平台是否支持所需操作。

目标文件存在时会发生什么？

对非目录目标，Go 文档规定 Rename 会替换它；目标是目录或跨平台限制不满足时，应按错误路径处理。