Go os.OpenFile 怎么避免并发创建配置文件时互相覆盖

我第一次遇到这个问题，是在一个服务首次启动时生成本地配置文件：两个实例几乎同时发现文件不存在，随后都拿到了可写文件句柄。结果有时是后一份内容覆盖前一份，有时是文件被截断后只剩半截配置。排查后发现，真正缺少的不是一把更大的锁，而是“只有一个实例可以完成首次创建”这个明确条件。

官方资料：https://pkg.go.dev/os#OpenFile

触发信号：首次启动时配置内容偶尔不一致

这类问题通常只在冷启动、扩容或两个命令同时运行时出现。单进程手工测试很难复现，因为“检查文件”和“打开文件”之间的空隙没有被放大。最常见的危险写法是先 os.Stat，再根据结果调用 os.OpenFile：两个实例都可能在第一次检查时看到不存在，然后一起进入创建分支。

即使不写 Stat，只使用 O_CREATE|O_WRONLY 也没有声明“我只接受新文件”。当路径已经存在时，调用仍可能成功打开它；如果后续写入从偏移 0 开始，两个实例就可能写到同一片区域。带上 O_TRUNC 时，风险还会变成重复截断。

快速判断：先看三个文件标志的职责

这里的关键是把“是否存在”的判断交给同一次 OpenFile 调用，而不是由应用层先观察再决定。Go 官方文档将 O_EXCL 定义为与 O_CREATE 一起使用、要求文件不能已存在的标志；它正好对应首次创建的判定边界。

处理步骤：用 O_CREATE|O_EXCL 抢一次创建权

下面的函数只负责创建缺失配置，并返回“我创建了”或“已有配置”。权限参数是新文件创建时使用的模式，实际结果还会受系统 umask 影响。创建成功后要及时关闭文件，不要把文件句柄泄漏到后续请求。

package main

import (
    "errors"
    "fmt"
    "io"
    "os"
    "strings"
)

// createConfigOnlyOnce 只尝试创建不存在的配置文件。
// 返回 created=false 表示路径已经存在，应交给读取分支处理。
func createConfigOnlyOnce(path string, content io.Reader) (created bool, err error) {
    // O_EXCL 必须和 O_CREATE 一起使用，避免把已有文件当成新文件打开。
    file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
    if err != nil {
        if errors.Is(err, os.ErrExist) {
            // 已有配置是并发初始化的正常结果，不要把它记录成系统故障。
            return false, nil
        }
        return false, fmt.Errorf("create config: %w", err)
    }

    // 写入失败时只清理本次成功创建的路径，避免误删原有配置。
    keepFile := false
    defer func() {
        if closeErr := file.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close config: %w", closeErr)
        }
        if err != nil && !keepFile {
            // 这是补偿清理，不等同于跨进程事务；失败时仍需记录告警。
            _ = os.Remove(path)
        }
    }()

    if _, err = io.Copy(file, content); err != nil {
        return false, fmt.Errorf("write config: %w", err)
    }
    keepFile = true
    return true, nil
}

func main() {
    // 示例使用内存内容，生产代码可换成序列化后的配置字节流。
    created, err := createConfigOnlyOnce("config.json", strings.NewReader(`{"mode":"safe"}`))
    if err != nil {
        panic(err)
    }
    fmt.Printf("created=%t\n", created)
}

这个函数把 os.ErrExist 处理成返回值，而不是让调用方解析错误字符串。只有本次 OpenFile 成功返回后，当前实例才拥有写入这条新路径的责任；已经存在的文件则不进入写入逻辑。

把“文件已存在”接到读取分支

创建函数返回 false, nil 后，调用方可以读取现有配置或进入自己的合并策略。不要为了“统一代码路径”再次用普通 O_CREATE 打开它，否则刚刚建立的独占条件就被绕开了。

package main

import (
    "bytes"
    "errors"
    "fmt"
    "os"
)

func ensureConfig(path string, defaults []byte) ([]byte, error) {
    created, err := createConfigOnlyOnce(path, bytes.NewReader(defaults))
    if err != nil {
        return nil, err
    }
    if created {
        // 当前实例已经写入默认配置，直接返回同一份内容。
        return defaults, nil
    }

    data, err := os.ReadFile(path)
    if err != nil {
        // 文件在创建结果与读取之间消失时，保留原始错误供上层重试或告警。
        if errors.Is(err, os.ErrNotExist) {
            return nil, fmt.Errorf("config disappeared after create race: %w", err)
        }
        return nil, fmt.Errorf("read existing config: %w", err)
    }
    return data, nil
}

这里特意把“已有配置”作为正常分支展开，便于把监控指标分成“首次创建成功”和“复用已有配置”两类。若读取到的文件可能仍在被另一个实例写入，就需要更高层的完成标记或原子替换协议，那已经超出本文限定的 O_CREATE 与 O_EXCL 创建竞态。

失败处理：写入或关闭失败时怎样回滚

独占创建成功不等于配置已经可用。写入可能遇到磁盘满、权限变化或 I/O 错误，关闭也可能返回错误。示例中的 defer 只在当前调用确实创建过路径时尝试删除，目的是减少半成品残留；它不是跨进程锁，也不能保证进程被强制终止时一定执行。

运行手册里建议把以下信号分开记录：

• 创建成功：首次初始化实例获得路径创建权。
• 文件已存在：竞争失败但属于预期分支，后续转读取或合并。
• 创建失败：目录不存在、权限不足或系统 I/O 故障，需要告警。
• 写入/关闭失败：当前实例创建了路径但没有完成配置，需要按业务决定清理、重试或人工介入。

回滚路径与复盘清单

如果上线后发现配置文件出现半截内容，先停止继续覆盖该路径的启动逻辑，保留现场文件和错误日志，再根据业务决定删除后重建。不要直接把 O_TRUNC 加回去“强制刷新”，那会把首次创建问题变成更明显的覆盖问题。

常见问题

只写 O_EXCL 不写 O_CREATE 可以吗？

不建议这样表达。官方定义里，O_EXCL 是与 O_CREATE 配合使用、要求文件不能已存在的标志；首次创建应明确写出两个标志。

收到 os.ErrExist 后可以直接覆盖吗？

不应该。这个错误说明当前实例没有取得新文件创建权，通常应读取已有配置；若业务需要更新配置，应使用独立的更新协议，不要把首次初始化和覆盖写混在一起。

O_CREATE|O_EXCL 能保证配置内容完整吗？

不能。它只保证创建路径时的排他条件。写入中途进程退出、读者过早读取等问题仍要由更高层的写入完成协议解决。

为什么不推荐先 os.Stat 再 os.OpenFile？

因为两个调用之间存在竞态窗口。另一个实例可以在这段时间创建文件，所以前一次 Stat 的结果不能代表下一次 OpenFile 仍然面对同样的状态。

对首次生成配置文件来说，我最后保留的判断很简单：创建权交给 O_CREATE|O_EXCL，os.ErrExist 进入已有配置分支，其它错误照实上报。这样既能避免多个实例把同一路径当成自己的新文件，也能让真正的磁盘和权限故障继续显现。