Go sync.Once-Value 怎么缓存初始化错误：一次性执行与重试边界

把配置、密钥或连接池做成惰性初始化时，最容易踩的坑不是并发安全，而是把“第一次失败”误当成“下一次会自动重试”。sync.OnceValue 返回的函数只会执行一次；初始化函数返回的错误如果被一起返回，后续调用也会看到同一个失败结果。

先看最小写法：一次初始化如何被并发复用

假设服务启动后第一次真正用到配置时才读取文件。没有 OnceValue 时，多个请求可能同时进入加载函数；有了它，调用方只接触一个普通的无参函数，初始化细节被收在闭包里。

var loadConfig = sync.OnceValue(func() (*Config, error) {
    return readConfig("/etc/demo/config.json")
})

func handleRequest() error {
    cfg, err := loadConfig()
    if err != nil {
        return fmt.Errorf("load config: %w", err)
    }
    return serve(cfg)
}

这里有两个值得记住的边界：函数没有参数，且返回值可以同时包含初始化结果和错误。第一次调用结束后，后面的调用不会再次执行 readConfig，而是复用已经保存的返回值。

并发调用时，等待的是同一次执行

sync.OnceValue 的价值不只是“加一把锁”。多个 goroutine 同时调用时，只有一个调用进入初始化函数，其余调用等待这次执行结束，然后拿到同一个值和同一个错误。

var calls atomic.Int32

load := sync.OnceValue(func() (string, error) {
    calls.Add(1)
    time.Sleep(20 * time.Millisecond)
    return "ready", nil
})

var wg sync.WaitGroup
for i := 0; i 

不要把 calls == 1 理解成所有错误场景都能自动恢复。它只说明这组调用共享了一次初始化。初始化函数返回什么，OnceValue 就缓存什么。

第一次失败也会被记住，重试必须换一个状态

举个很常见的线上场景：服务刚启动时配置存储路径还没挂载完成，初始化函数直接返回错误，后续所有调用拿到的永远是第一次返回的错误，完全不会重新走读取配置的逻辑。这种语义对要求“绝对只初始化一次”的资源很安全，却不适合网络临时抖动、配置热加载，或是出问题人工修复后要继续尝试的任务。

var attempts atomic.Int32

load := sync.OnceValue(func() (string, error) {
    n := attempts.Add(1)
    if n == 1 {
        return "", errors.New("config not mounted")
    }
    return "ready", nil
})

_, firstErr := load()
_, secondErr := load()
// attempts 仍然是 1，secondErr 与 firstErr 表示同一次初始化失败。

如果业务确实需要支持重试，可以把 OnceValue 放进受管控的可替换状态槽位里。要重试时先修复完错误根因，再直接替换整个闭包对象；不要在原来的初始化函数里偷偷维护重试计数，否则 OnceValue“只会执行一次”的语义承诺会被破坏，内部藏的循环逻辑也很难排查。

把重试做成显式操作，测试边界会更清楚

下面这个简单封装，把“当前在用的加载函数”和“替换操作”都放到同一个结构体里。生产环境使用通常还要补上权限校验、重试冷却、监控指标埋点，但核心的状态切换逻辑要先保证单一职责。

type Loader struct {
    mu   sync.RWMutex
    load func() (*Config, error)
}

func NewLoader(read func() (*Config, error)) *Loader {
    return &Loader{load: sync.OnceValue(read)}
}

func (l *Loader) Get() (*Config, error) {
    l.mu.RLock()
    load := l.load
    l.mu.RUnlock()
    return load()
}

func (l *Loader) Retry(read func() (*Config, error)) {
    l.mu.Lock()
    l.load = sync.OnceValue(read)
    l.mu.Unlock()
}

替换函数时要考虑正在执行的旧加载逻辑，这个示例让已经拿到旧函数的请求走完旧流程，新进来的调用直接使用新函数；如果配置切换要求所有请求原子同步生效，还需要在业务层额外增加版本号机制，或是设置短时间的发布屏障。

几个容易误用的地方

不要把带请求参数的查询塞进 OnceValue

OnceValue 本身不带入参，只适合生成全局唯一、或是生命周期完全固定的结果。用户 ID、租户 ID、请求头这类和请求上下文绑定的输入如果参与结果计算，应直接使用显式缓存或普通函数，不然第一次请求算出的结果会意外覆盖所有后续请求的返回值，出问题很难排查。

不要把错误缓存当成重试策略

缓存初始化错误可以避免故障期间大量并发请求反复打垮下游依赖，但它本身不是重试器。要走重试流程时，先把失败根因、触发重试的操作者、新旧状态的执行次数都记录好，再替换闭包生成新的 OnceValue 状态，别放任调用方靠反复调用碰运气恢复，凭空产生大量无效流量。

测试不要只断言返回值

至少用原子计数器确认初始化函数执行次数；再让第一次返回错误，确认第二次仍是同一状态；最后调用显式重试并确认新闭包只执行一次。并发测试还应运行 go test -race。

最后用一条检查清单决定是否适合

如果初始化无参数、成功结果可以长期复用，并且失败后不需要自动再次尝试，sync.OnceValue 通常是清晰的最小方案。若任务要按时间重试、按租户隔离、按版本热更新，应该把状态机或缓存边界显式写出来。

实际验收的时候只要确认三个问题就够了：初始化函数最多会执行几次；第一次失败后所有调用方拿到的返回是什么；人工修复问题之后由谁负责创建新的执行状态。三个问题都有明确答案，再把 OnceValue 放进共享服务对象里使用。

相关问题

sync.OnceValue 和 sync.Once 有什么区别？

sync.Once 只负责执行一次，结果需要自己放到变量里；sync.OnceValue 直接返回一个可调用的缓存函数，更适合封装单个值和错误。

初始化函数 panic 会怎样？

你要把初始化逻辑里可能出现的 panic 当成初始化失败的特殊分支单独设计和测试，不要依赖调用方反复调用来从异常状态里恢复。对外暴露这个能力之前先定好处理策略，决定是让 panic 继续上抛，还是在更外层统一转换成可观测的启动失败告警。