Go sync.Once 初始化失败后为什么不能再次尝试怎样构造最小复现

如果把一个可能失败的初始化函数直接交给 sync.Once.Do，第一次调用即使返回错误，后续调用也不会自动重试。原因不是错误被“缓存后可刷新”，而是 sync.Once 的契约只有一个：让这段函数最多执行一次；函数返回、甚至发生 panic 后，Once 都会被视为已经完成。需要重试时，应把“只执行一次”和“失败可重试”拆成两种不同的状态模型。

调用 sync.Once 触发初始化失败后状态永久固化，没有官方提供的重置入口，既不能重试初始化流程，也不能通过常规手段回滚标记位，业务侧要提前兜底这类异常场景。

先把问题缩小成“最多一次”而不是“直到成功”

sync.Once 适合配置加载、不可变表初始化或一次性注册这类动作：无论多个 goroutine 何时到达，都只需要一个调用者执行初始化，其他调用者等待它完成。它保证的是执行次数和同步可见性，不保证初始化一定成功，也不定义失败后的重试策略。

下面的最小项目只保留三个变量：一个 sync.Once、一个初始化错误和一次尝试计数。把计数放在函数体里，是为了让“是否重新进入初始化函数”有清晰的观察点：

package main

import (
    "errors"
    "fmt"
    "sync"
)

var (
    once     sync.Once
    initErr  error
    attempts int
)

func initResource() {
    // 计数只用于观察初始化函数实际进入了几次。
    attempts++
    initErr = errors.New("配置中心暂时不可用")
}

func loadResource() error {
    once.Do(func() {
        // Do 不会根据返回值判断成功或失败；这里的错误由外层保存。
        initResource()
    })
    return initErr
}

func main() {
    // 两次调用使用同一个 Once，第二次不会重新执行 initResource。
    firstErr := loadResource()
    secondErr := loadResource()
    fmt.Println(firstErr, secondErr, attempts)
}

这段代码中的关键不是错误文本，而是 attempts 的语义：它代表初始化函数真正被调用了多少次。按照 sync.Once 的契约，第二次 loadResource 仍然能读到外层保存的错误，但不会让计数再次增加。

最小复现里第二次为什么没有重新尝试

把调用过程拆开看，会发现“返回错误”和“允许下一次进入”是两件互不相同的事。第一次调用进入函数，函数把失败写入 initErr，然后 Do 将这次调用标记为完成；第二次调用只看到 Once 已完成，于是跳过函数体，直接继续读取外层状态。

这也是一个容易误判的地方：如果调用方只检查返回值，会觉得“第二次仍然报错，所以可能重试了”。真正能证明重试发生的证据应该是初始化函数内部的计数、日志或一次性副作用。文章中的计数是静态示例，用来说明应当观察哪一层，不把图示当成实际运行结果。

从并发角度看，Once 的价值正是让等待者不会在初始化尚未结束时读取半成品。它不能同时承担“失败后重新开放入口”的职责，否则已经返回的调用者和正在等待的调用者会看到不一致的状态。

不要用清空错误变量的方式“修复”重试

常见的错误修复是：失败后把 initErr 设为 nil，或者重新声明一个局部变量，期待下一次 Do 能再次执行。这只改变了调用方读取到的值，没有改变 Once 内部的完成状态；结果可能变成“表面没有错误，但资源其实从未初始化”。

另一个风险是把新的 sync.Once 直接赋值给共享变量。除非整个生命周期有严格的所有权和同步协议，否则读写 Once 本身会引入数据竞争，也会让已经拿到旧状态的调用者和新状态调用者分裂。需要重试时，应该把状态迁移写成一个受保护的接口，而不是重置同步原语。

确实需要重试时改用显式状态和互斥保护

如果依赖的是会暂时不可用的网络服务、配置中心或文件挂载，需求通常是“失败后下一次调用可以再试”。可以让每次调用在锁内检查状态，成功后固定为 ready，失败则保留 failed 并释放锁，让下次调用重新尝试。下面的示例只演示状态边界，真实项目还应加入退避、超时和最大尝试次数。

package main

import (
    "errors"
    "sync"
)

type loader struct {
    mu      sync.Mutex
    ready   bool
    attempts int
}

func (l *loader) load() error {
    l.mu.Lock()
    defer l.mu.Unlock()

    // 成功状态是稳定结果，后续调用直接复用已经准备好的资源。
    if l.ready {
        return nil
    }

    l.attempts++
    if err := fetchConfig(); err != nil {
        // 失败不把 ready 改成 true，下一次调用仍然拥有重试机会。
        return err
    }
    l.ready = true
    return nil
}

func fetchConfig() error {
    // 这里代表可能暂时失败的外部依赖，示例不执行真实网络请求。
    return errors.New("配置中心暂时不可用")
}

这个版本的关键是状态迁移可读：ready=false 时允许尝试，失败后仍是 false，成功后才切换成 true。锁保证同一时间只有一个调用者推进迁移；如果不希望其他调用者长时间等待，可以把外部请求移到锁外，并额外设计“加载中”状态、版本号或单飞机制，不能简单删除锁。

用四个问题决定该选 Once 还是可重试初始化

在代码评审时，可以先回答下面四个问题。如果失败代表进程配置不可用、继续运行没有意义，那么 sync.Once 仍然合适，调用方只需稳定地传播失败。如果依赖会恢复且业务允许继续工作，则应保留失败状态，并为重试、退避和并发合并写出明确规则。

• 初始化函数失败后，业务是否允许当前进程继续提供服务？
• 失败结果是否可以在后续时间点重新获得？
• 重试时是否需要限制频率、超时或最大次数？
• 成功后的资源是否会被替换，还是只需要准备一次并永久复用？

常见问题

sync.Once.Do 里的函数返回 error 后，Once 会重置吗？

不会。Do 本身没有返回值约定，也不会根据外层保存的 error 改变完成状态；初始化函数执行结束后，后续调用会跳过它。

初始化函数 panic 后还能再次调用吗？

不能把 sync.Once 当成 panic 重试器。需要恢复或重试时，应在 Once 外部捕获并设计新的状态边界；是否传播 panic 则由具体封装方式决定。

把 sync.Once 放进结构体后重新赋值可以吗？

不建议把重新赋值当成常规重试方案。同步原语需要稳定的共享身份，重置它会引入并发访问和生命周期问题；更清晰的做法是使用互斥锁保护显式状态。

什么时候最适合使用 sync.Once？

当动作只需要执行一次，失败后也不应在同一生命周期里偷偷重做，并且所有调用者都要看到同一次完成结果时，sync.Once 才与需求匹配。