Go 并发配置初始化如何避免重复执行：双返回值闭包与错误生命周期

服务启动后不一定马上需要完整配置，很多 Go 服务会把读取文件、解析环境变量或建立客户端的动作推迟到第一次请求。问题也常常出在这里：十几个 goroutine 同时触发初始化，失败结果被反复包装，排查日志反而看不出到底执行了几次。

如果这段初始化只允许执行一次，而且调用方需要同时拿到“值”和“错误”，sync.OnceValues 是标准库里很顺手的选择。它会让初始化函数只运行一次，并把返回的两个结果交给后续并发调用；其中的错误也会被原样复用。

OnceValues 适合“只初始化一次、结果可以共享”的资源；它不是失败重试器。第一次返回的错误会成为这个实例的最终结果，想重试就要创建新的 OnceValues 实例。

先看一个并发初始化现场

假设服务只在第一次请求到来时读取 config.json。传统写法通常把 sync.Once、配置值和错误拆成三个变量，代码不长，但很容易漏掉错误的同步或把“是否初始化过”和“初始化是否成功”混在一起。

type Config struct {
    Endpoint string
}

var (
    once   sync.Once
    config Config
    err    error
)

func getConfig() (Config, error) {
    once.Do(func() {
        config, err = loadConfig()
    })
    return config, err
}

这段代码可以工作，但初始化逻辑、共享状态和返回逻辑彼此分散。更麻烦的是，后面如果有人把 err 改成“下次再试”，就会改变 sync.Once 原本的语义。

OnceValues 把这组状态收进一个闭包：

var getConfig = sync.OnceValues(func() (Config, error) {
    return loadConfig()
})

func handler() error {
    cfg, err := getConfig()
    if err != nil {
        return fmt.Errorf("load config: %w", err)
    }
    return callBackend(cfg.Endpoint)
}

这里的关键不是语法更短，而是 loadConfig 的调用边界变得清楚：所有调用方只拿 result 和 error，不再直接接触一次性状态。

OnceValues 的一次性语义到底缓存了什么

根据 sync 包文档，OnceValues(f) 返回一个可并发调用的函数。第一次调用时执行 f，之后调用直接返回同一组返回值。对双返回值初始化来说，这意味着配置和错误是一个整体。

因此，不能把它当成“缓存成功结果”的工具。初始化函数返回错误时，这个错误同样属于该实例的结果。把错误打印得更友好可以放在 handler，但不能据此期待下一次 getConfig() 会重新执行 loadConfig。

错误缓存后，重试为什么必须换实例

这是最容易写错的地方。下面的例子中，第一次读取失败后，第二次调用看起来像重试，实际上只是在读取已经缓存的错误：

getConfig := sync.OnceValues(func() (Config, error) {
    return loadConfig()
})

_, firstErr := getConfig()
_, secondErr := getConfig()
// loadConfig 只执行一次。
// firstErr 与 secondErr 来自同一组缓存结果。

如果故障来自临时文件不可读、依赖服务尚未就绪或环境变量尚未注入，应该把“可重试策略”放在更外层：每次重试都新建一次性函数，或者干脆使用带退避的普通函数。不要通过修改闭包里的变量破坏一次性边界。

func loadConfigWithRetry(maxAttempts int) (Config, error) {
    var lastErr error
    for attempt := 0; attempt 

这个示例表达的是边界，不代表所有重试都应该这样写。若初始化很重，反复创建并调用闭包可能不是好方案；更常见的生产设计是把启动探针、重试退避和最终的一次性发布分开。先判断资源是否真的允许“失败后重试”。

用测试确认并发调用只执行一次

测试不要只调用一次然后断言返回值。给 loadConfig 加一个受保护的计数器，再让多个 goroutine 同时调用返回函数，才能证明一次性语义真的覆盖了并发入口。

func TestOnceValuesConcurrent(t *testing.T) {
    var calls atomic.Int32
    getConfig := sync.OnceValues(func() (Config, error) {
        calls.Add(1)
        return Config{Endpoint: "https://api.example.test"}, nil
    })

    var wg sync.WaitGroup
    for range 20 {
        wg.Go(func() {
            cfg, err := getConfig()
            if err != nil || cfg.Endpoint == "" {
                t.Errorf("cfg=%+v err=%v", cfg, err)
            }
        })
    }
    wg.Wait()

    if got := calls.Load(); got != 1 {
        t.Fatalf("loadConfig calls = %d, want 1", got)
    }
}

如果项目 Go 版本低于支持 WaitGroup.Go 的版本，可以改回 Add(1) 与 goroutine 内的 Done()；这不影响 OnceValues 的验证目标。测试还应补一条首次返回错误的用例，确认第二次调用仍得到同一个错误语义。

几个容易混淆的边界

• 需要按 key 懒加载：OnceValues 只对应一个闭包实例；多租户或多配置 key 应该管理多个实例，而不是把 key 偷塞进一次初始化。
• 需要刷新配置：一次性闭包没有刷新入口。刷新应换成带版本、过期时间或显式替换的配置对象。
• 初始化函数会递归调用自己：不要在 loadConfig 内再次调用同一个返回函数，否则会形成等待自身完成的死锁风险。
• 初始化函数 panic：sync 文档明确说明，后续调用会复现同一个 panic；若需要把失败转换成可恢复错误，应在初始化函数内做好边界设计。

相关问题

OnceValues 和 sync.Once 应该怎么选？

只有副作用、没有返回值时用 Once 足够；需要把一次初始化产生的两个结果一起交给调用方时，OnceValues 更直接。

OnceValues 返回 error 后能不能自动重试？

不能。错误是返回值的一部分，会和其他结果一起缓存。自动重试必须由外层策略控制，或创建新的 OnceValues 实例。

并发调用会不会让初始化函数执行多次？

不会。返回函数允许并发调用，初始化函数只执行一次；其他调用会等待这次初始化完成后读取结果。

什么时候不适合用 OnceValues？

需要定时刷新、按请求重试、按 key 建立多个资源，或者错误不能长期复用时，不要把一次性闭包当成通用缓存。

把一次性边界写进代码审查清单

审查这类代码时，先问四个问题：初始化是否真的只需要一次？失败结果是否可以被后续调用接受？是否有明确的重试或刷新边界？并发测试是否证明 loadConfig 只执行一次？四个答案都清楚，再决定使用 sync.OnceValues。

它解决的是“同一个初始化结果如何安全共享”，不是“任何失败都自动恢复”。把这条边界留在代码里，后续维护者就不容易把缓存错误误当成重试成功。