Go os.File.Sync 与 rename 如何配合：让配置文件替换真正落盘

服务启动时读到半截配置，往往不是 JSON 解析器的问题，而是更新配置时直接覆盖了正在使用的文件。Go 里把新内容写进临时文件、调用 File.Sync，再用 os.Rename 替换正式文件，能把“读到半文件”的窗口压到最低；如果还要覆盖目录项本身的持久化风险，就要在重命名后同步父目录。

可恢复的配置替换顺序是：临时文件写完并执行 File.Sync，关闭文件后调用 os.Rename，最后打开父目录并同步目录项；只调用 Write 或只调用 Rename，都不能表达完整的落盘意图。

为什么“写成功”仍可能留下旧配置

os.WriteFile 或 File.Write 返回 nil，只说明这次调用没有报告错误，不等于数据已经稳定地跨过了操作系统缓存和存储设备的边界。更麻烦的是，直接写正式文件时，进程在清空旧内容与写入新内容之间退出，下一次启动可能读到一个语法完整性都不保证的半文件。

所以这里要拆开两个问题：文件内容有没有写完，文件名切换有没有完成。前者由 File.Sync 参与确认，后者由 os.Rename 完成。两件事混成一次覆盖写，排障时很难判断到底是哪一段出了问题。

用临时文件隔离完整内容，再切换正式文件

下面的示例把临时文件放在目标配置所在目录。这样做不是为了好看：同一文件系统内的重命名通常更适合表达“从旧文件切换到新文件”，也避免临时文件创建在系统临时目录后无法直接重命名。

package configfile

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

func ReplaceConfig(path string, data []byte) error {
    dir := filepath.Dir(path)
    tmp, err := os.CreateTemp(dir, ".config-*")
    if err != nil {
        return err
    }
    tmpName := tmp.Name()
    keepTemp := true
    defer func() {
        if keepTemp {
            _ = os.Remove(tmpName)
        }
    }()

    if _, err = tmp.Write(data); err != nil {
        _ = tmp.Close()
        return err
    }
    if err = tmp.Sync(); err != nil {
        _ = tmp.Close()
        return err
    }
    if err = tmp.Close(); err != nil {
        return err
    }
    if err = os.Rename(tmpName, path); err != nil {
        return err
    }
    keepTemp = false

    d, err := os.Open(dir)
    if err != nil {
        return fmt.Errorf("open config directory: %w", err)
    }
    defer d.Close()
    return d.Sync()
}

这段代码里，os.CreateTemp 先得到一个同目录临时文件，tmp.Write 写入完整内容，tmp.Sync 把文件同步请求发下去，随后 tmp.Close 释放文件描述符。只有这些步骤成功，才进入 os.Rename；重命名之后，再对父目录调用 d.Sync。

为什么临时文件必须和目标文件同目录

os.Rename 的语义受文件系统边界影响。把临时文件创建在目标目录，能让替换动作保持在同一目录和文件系统中；如果跨文件系统，重命名可能返回错误，这时不能把它偷偷改成“复制后删除”，因为复制删除又重新打开了半文件窗口。

把 File.Sync、os.Rename 和目录同步分开验收

生产代码里不要只测返回值为 nil。可以把每一步当作独立验收点：File.Sync 失败时临时文件仍应清理，os.Rename 失败时旧配置不能被删除，目录同步失败时则要把风险记录清楚，决定是否阻断发布或进入人工复核。

这里别急着把所有错误都包装成“保存失败”。日志里至少保留阶段名和目标路径，例如 sync temp file、rename config、sync config directory。这样下次遇到重启后配置回退，能快速分辨是文件数据、文件名还是目录项的问题。

验收时可以把状态明确记成“旧配置仍可读、临时文件已写完并关闭、正式配置已经成为当前入口”，这样日志和测试结果不会只剩一句“保存成功”。

测试时别只验证当前进程能读到新内容

一个普通单元测试可以检查替换后读取到新 JSON，但这只能证明当前调用链工作。更接近实际的验收要覆盖三个边界：写入空字节时是否仍能得到合法配置、重命名失败时旧文件是否保留、临时文件是否会在错误返回后残留。

func TestReplaceConfig(t *testing.T) {
    dir := t.TempDir()
    path := filepath.Join(dir, "app.json")
    if err := os.WriteFile(path, []byte(`{"port":8080}`), 0600); err != nil {
        t.Fatal(err)
    }
    if err := ReplaceConfig(path, []byte(`{"port":9090}`)); err != nil {
        t.Fatal(err)
    }
    got, err := os.ReadFile(path)
    if err != nil {
        t.Fatal(err)
    }
    if string(got) != `{"port":9090}` {
        t.Fatalf("got %s", got)
    }
}

如果业务允许旧版本回退，可以在 os.Rename 前把旧文件复制成带版本号的备份，并限制备份数量；但备份策略属于业务层，不要用它替代 File.Sync 和目录同步。

常见问题

只调用 os.Rename，不调用 File.Sync，可以吗？

它能减少读到半文件的概率，但不能表达新文件内容已经提交到稳定存储的意图。对可重新生成的缓存配置风险较低，对启动关键配置不够稳妥。

为什么 d.Sync 失败不能直接忽略？

它对应父目录中的文件名变化。是否阻断发布要看业务能否接受重启后仍看到旧名字，但至少应该记录阶段和错误，不能把它当成普通日志噪声。

临时文件名应该固定吗？

不建议固定。使用 os.CreateTemp 生成唯一名称，能避免两个更新进程互相覆盖临时文件；如果还需要禁止并发发布，应在业务层设计明确的协调机制。

最后的检查清单

• 临时文件和正式文件位于同一目标目录。
• 写入后检查 File.Sync 和 Close 返回值。
• 只有临时文件准备完成后才调用 os.Rename。
• 重命名后按业务重要性调用父目录的 Sync。
• 为写入、文件同步、重命名、目录同步分别记录可检索的错误阶段。