Go sync.Once 怎么让失败初始化可以被明确记录

服务启动时经常要加载配置、建立连接或读取本地密钥。把这段逻辑放进 sync.Once 后，多个 goroutine 不会重复初始化；但 Do 没有 error 返回值，初始化函数一旦失败，后续调用也不会自动再试。正确做法是让初始化函数把结果和错误写入同一份共享状态，再由封装方法统一返回。

把“只执行一次”和“失败怎么处理”拆成两件事：用 sync.Once 保证写状态只发生一次，用 error 保存第一次失败；调用方根据这个稳定错误决定降级、报警或终止启动。

先明确 sync.Once 的一次性保证和错误语义

sync.Once 的语义是某个实例的 Do 最多调用一次函数。多个调用会等待这一次函数返回；函数正常返回后，后续调用直接结束。即使函数内部遇到错误，只要它没有继续向外 panic，Once 也不知道“失败”这个业务含义。

因此下面这种写法会把错误吞掉：

var once sync.Once

func initService() {
    once.Do(func() {
        // 错误没有出口，失败后也不会自动重试
        _ = loadConfig()
    })
}

官方实现还明确说明：如果函数 panic，Do 会把它视为已经返回，后续调用不会再次执行函数。初始化失败是预期业务分支时，返回并保存 error 比用 panic 表达更清楚。

把结果和错误放进与 Once 同生命周期的状态

可以定义一个小型加载器，让 once、配置指针和错误一起存在。关键点不是加更多锁，而是保证写入发生在 Do 的函数体内，读取发生在 Do 返回之后：

type Config struct {
    Endpoint string
}

type ConfigLoader struct {
    once sync.Once
    cfg  *Config
    err  error
}

func (l *ConfigLoader) load() {
    l.once.Do(func() {
        // 只在首次调用时读取配置，并保留第一次失败
        cfg, err := readConfig()
        if err != nil {
            l.err = fmt.Errorf("load config: %w", err)
            return
        }
        l.cfg = cfg
    })
}

这里的 err 不需要用 atomic.Value 再包一层：所有读取都在 load 中的 Do 返回后完成，初始化函数的完成与后续 Do 返回之间有同步关系。若状态对象会被复制，必须在第一次使用前完成复制，实际项目更适合始终传递它的指针。

用一个入口让并发调用拿到一致结果

不要让业务代码直接访问 once、cfg 和 err 三个字段。封装成返回值后，调用方既能处理错误，也不会误以为第二次调用会触发重试：

func (l *ConfigLoader) Get() (*Config, error) {
    l.load()
    // Do 返回后再读取共享结果，所有调用者看到同一份状态
    if l.err != nil {
        return nil, l.err
    }
    return l.cfg, nil
}

var loader ConfigLoader

func handleRequest() error {
    cfg, err := loader.Get()
    if err != nil {
        // 配置是启动必需项时，直接向上返回并保留根因
        return err
    }
    return callBackend(cfg.Endpoint)
}

如果十个 goroutine 同时调用 Get，只有一个会执行 readConfig，其他调用会等它结束，然后拿到同一个 cfg 或同一个 err。错误用 %w 包装，后续仍可用 errors.Is 或 errors.As 判断根因。

按错误类型决定是否需要新的重试边界

sync.Once 适合“进程生命周期内只初始化一次”的对象，例如不可变配置或固定的本地资源。如果错误来自临时网络故障，继续复用同一个 Once 就会永久记住失败。这不是代码 bug，而是一次性语义和重试需求不匹配。

若确实需要重试，应把“尝试次数、退避、取消和并发合并”设计成独立组件；或者在确认旧状态不再被读取后，整体创建新的 ConfigLoader。不要为了重置而直接复制已经使用过的 sync.Once，也不要并发替换仍在被调用的共享指针。

常见问题

初始化函数返回 error 后，sync.Once 会自动重试吗？

不会。Do 只有 func() 参数，函数返回后这次执行就结束；错误必须由外部状态保存。

把 error 写进全局变量会有数据竞争吗？

只要写入发生在 Do 的函数体内、读取发生在 Do 返回之后，并且 Once 实例没有被复制，就可以利用它提供的同步关系安全读取。

什么时候应该改用 sync.OnceValues？

如果项目使用支持泛型 Once API 的 Go 版本，sync.OnceValues 可以直接缓存一个值和一个 error；但它仍然只执行一次，临时故障的重试边界仍需单独设计。