sync.OnceValues 如何缓存带错误的初始化结果

我在把“只初始化一次”的配置读取改成并发安全版本时，最容易漏掉的不是锁，而是 error 的生命周期：文件第一次读取失败后，后续调用究竟应该重试，还是继续看到同一个失败结果？sync.OnceValues 的答案很明确：它只执行初始化函数一次，并把返回的两个值一起缓存，包括非空的 error。

官方文档：https://pkg.go.dev/sync#OnceValues

如果初始化失败是稳定事实，可以用 sync.OnceValues 把值和错误绑定成一次性结果；如果失败可能被外部修复，就不要把可重试操作放进这个缓存。

从 sync.Once 手写初始化看值与错误为何容易分离

旧代码常用一个 sync.Once 加两个包级变量。这样能保证函数只跑一次，但调用者必须自己保证“值”和“错误”始终属于同一次初始化，否则就会出现读到旧值却拿到新错误的维护风险。

var once sync.Once
var cfg Config
var cfgErr error

func ConfigValue() (Config, error) {
    once.Do(func() {
        // 初始化只执行一次，同时写入结果和错误。
        cfg, cfgErr = loadConfig()
    })
    return cfg, cfgErr
}

这段写法并非错误，但状态分散、重复样板较多。更重要的是，once 一旦完成，哪怕 loadConfig 返回错误，下一次也不会自动再试。

用 sync.OnceValues 返回并缓存值与 error

Go 1.21 起可以直接让闭包返回二元组。下面的例子把文件内容和读取错误放在同一个一次性结果中；多个 goroutine 可以并发调用，真正的读取仍只有一次。

var readSchema = sync.OnceValues(func() ([]byte, error) {
    // 文件不存在时，错误也会成为缓存结果的一部分。
    return os.ReadFile("schema.json")
})

func Schema() ([]byte, error) {
    // 后续调用直接复用同一份 []byte 和 error。
    return readSchema()
}

这里的关键不是“缓存文件”本身，而是闭包代表的初始化边界。若首次读取成功，后续调用拿到同一组结果；若首次读取失败，后续调用也会得到同一个失败结果。需要刷新时，应重新创建一个新的 OnceValues 闭包，而不是试图重置它。

并发等待、错误复用与 panic 复用分别意味着什么

第一次调用尚未结束时，其他并发调用会等待这次初始化完成。初始化返回后，它们读取同一组结果，不会各自再执行一遍。文档还规定：如果初始化函数发生 panic，返回的函数会在每次调用时以相同值再次 panic；因此不要把可能随时 panic 的不受控代码塞进公共缓存。

按错误是否可恢复决定是否采用

判断标准可以很实际：配置文件路径写错、必需格式不满足、运行时能力探测失败，这些结果在本进程生命周期内通常没有理由改变，适合缓存；临时 DNS、服务端短暂不可用、凭据轮换中的网络请求，则应该由带退避和超时的普通函数处理，或者按请求周期重新创建缓存。

我会在代码评审中检查四件事：项目的 Go 版本是否至少为 1.21；闭包捕获的输入是否真的固定；返回的资源是否需要调用方关闭；错误是否值得在整个进程中保持不变。尤其是 *os.File、数据库连接这类有生命周期的对象，缓存初始化结果不等于替调用方管理关闭。

相关问题

sync.OnceValues 会因为返回 error 而再次执行吗？

不会。只要初始化函数已经返回，成功或失败都算完成；后续调用直接复用结果。

如何让 OnceValues 重新加载配置？

把缓存闭包封装在一个可替换的配置对象中，切换配置时创建新的 sync.OnceValues；不要修改已经使用过的内部状态。

OnceValues 和 OnceValue 怎么选？

只有一个结果时用 OnceValue；需要把数据与错误、状态或元信息成对返回时用 OnceValues。