Go os 怎样用 File.Sync 处理持久化边界

在配置文件、索引文件或追加日志时，最容易误判的一点是：Write 返回成功，并不等于数据已经到达稳定存储。os.File.Sync 的作用，是把当前文件内容提交到稳定存储；因此真正需要“这一刻即使机器掉电也尽量保住”的位置，才是同步边界。

实战中可以这样分工：Write 负责把字节交给文件对象，Sync 负责提交文件内容，Close 负责结束文件句柄并继续报告关闭错误。若采用“临时文件写入后替换”的方式，还要把文件内容和父目录中的目录项看成两个对象。

为什么 Write 成功还不等于已经持久化

文件写入通常会经过操作系统或文件系统缓存。Write 的成功只说明本次调用接受了这些字节；Sync 才是向稳定存储提交当前文件内容的明确动作。下面这张图只表达对象之间的静态关系，不是终端截图，也不是运行结果。

如果业务要求“每条记录单独可恢复”，可以每条记录写完后同步；如果允许丢失最近一小批记录，则可以累积多条后再同步。后者减少同步次数，但也把这批数据放进了同一个持久化风险窗口。

把 Sync 放到真正的提交点

一个可复用的写入函数应当同时处理短写、写入错误、同步错误和关闭错误。不要只检查 Write，也不要把 Close 当作 Sync 的替代品：

package storage

import (
    "fmt"
    "io"
    "os"
)

func writeAndSync(path string, data []byte) (err error) {
    // 创建或截断目标文件，真正的提交点由后面的 Sync 决定。
    f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
    if err != nil {
        return fmt.Errorf("open %s: %w", path, err)
    }
    defer func() {
        // 前面的操作都成功时，Close 错误也不能被静默丢掉。
        if closeErr := f.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close %s: %w", path, closeErr)
        }
    }()

    // n 可能小于 data 长度，短写不能当作完整提交。
    n, err := f.Write(data)
    if err != nil {
        return fmt.Errorf("write %s: %w", path, err)
    }
    if n != len(data) {
        return fmt.Errorf("write %s: %w", path, io.ErrShortWrite)
    }

    // 把当前文件内容提交到稳定存储，并保留同步失败原因。
    if err := f.Sync(); err != nil {
        return fmt.Errorf("sync %s: %w", path, err)
    }
    return nil
}

这里使用命名返回值，是为了让延迟执行的 Close 错误能够补充到返回结果中。若业务不允许任何数据丢失，调用方还应把这个函数的错误当作提交失败处理，而不是继续更新内存中的“已保存”状态。

短写和同步错误应该怎样定位

排查时可以沿着三个问题走：返回的 n 是否等于输入长度？Write 是否返回错误？Sync 是否返回错误？三者分别对应数据是否完整交给文件对象、写入过程是否失败、文件内容是否完成同步。

如果只在开发机上观察文件重新打开后能读到内容，仍不能推出掉电后的持久化结论，因为重新打开读取可能仍受缓存和底层设备策略影响。代码中至少要保留 Sync 的错误，并在错误发生时让上层决定重试、回滚或标记任务失败。

替换文件时还要看目录项边界

配置文件常见的安全写法是先写临时文件，再同步临时文件内容，最后用 os.Rename 替换目标名。这能把“半截内容暴露给读取者”的风险降下来，但它没有把所有持久化对象合并成一个对象。

File.Sync 关注的是文件内容；Rename 改变的是名称映射，父目录中的目录项因此成为另一个需要考虑的持久化对象。跨平台程序应先明确自己的崩溃一致性目标，再依据目标系统的文件系统语义决定是否还要同步父目录；不要把“临时文件已经 Sync”写成“替换操作已经全部落盘”的绝对结论。

常见疑问

每次 Write 后都必须 Sync 吗？ 不必须。频率取决于允许丢失的数据窗口；按记录同步更稳妥，按批次同步通常更省成本。

调用 Close 就够了吗？ 如果需求只是释放句柄，Close 是必要动作；如果需求是明确提交文件内容到稳定存储，应显式调用 Sync 并检查错误。

O_SYNC 能替代 File.Sync 吗？ 它是打开文件时请求同步写入的另一种策略，但会改变写入成本和平台行为。本文场景更适合把提交点写在代码里，让持久化边界清晰可见。

总结：把 Write 看作交付字节，把 Sync 看作提交文件内容，把 Close 看作结束句柄并收集最后错误；涉及临时文件替换时，再单独评估父目录目录项的持久化边界。