Go sync.OnceValue 界定 panic 的重复触发

Go 1.21 在 sync 包中加入了 OnceValue。它经常被用于延迟初始化，但有一个容易误读的边界：初始化函数只会真正执行一次；如果这次执行发生 panic，返回的函数在后续调用中仍会以同一个值再次 panic。这不是初始化函数被重新执行，而是失败结果被稳定地传播。

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

把 OnceValue 看成“成功值缓存 + 失败 panic 记忆”更准确。需要把失败转成错误时，在直接调用边界使用 defer/recover；需要重试时，重新创建一个新的 OnceValue 返回函数。

OnceValue 的合同不是“失败后再试一次”

sync.OnceValue(f) 返回一个无参数函数。第一次调用时，它会调用 f 并缓存返回值；并发调用也共享同一份一次性状态。官方文档同时明确：如果 f panic，返回函数会在每次调用时以同一个值 panic。

因此要分开记两件事：

• 执行次数：初始化闭包最多真正进入一次。
• 传播次数：调用返回函数多少次，失败的 panic 就可能向外传播多少次。

用一个最小示例区分两种次数

下面的例子给 panic 使用一个固定的 error 实例，并在调用方恢复它。这样既能观察初始化闭包只进入一次，也能观察两次调用拿到的是同一个 panic 值。

package main

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

func main() {
    panicValue := errors.New("config missing")
    runs := 0

    load := sync.OnceValue(func() string {
        runs++ // 只统计初始化闭包真正执行的次数
        panic(panicValue) // 失败值会被 OnceValue 记住
    })

    panics := make([]any, 0, 2)
    for range 2 {
        func() {
            defer func() {
                panics = append(panics, recover()) // 在直接调用边界取回 panic 值
            }()
            _ = load() // 第二次调用不会重新进入初始化闭包
        }()
    }

    fmt.Println(runs)                 // 预期为 1
    fmt.Println(panics[0] == panics[1]) // 预期为 true
}

这个结果的重点是：runs 为 1，说明闭包没有重跑；两个恢复出来的值相同，说明失败状态被重复传播。若直接让 panic 穿出函数，第二次调用同样会中断调用方，不能把这种行为理解成“OnceValue 自动重试了两次”。

recover 应该放在 OnceValue 调用边界

recover 只有在 panic 发生的同一 goroutine 中、并由正在执行的 deferred 函数调用时才有效。工程上更稳妥的做法，是把一次性函数当作普通依赖传入，在最靠近调用点的边界统一转换为错误，而不是把 recover 藏进初始化闭包里。

func safeLoad(load func() string) (value string, err error) {
    defer func() {
        if p := recover(); p != nil {
            // 只在边界转换预期的初始化失败，避免吞掉正常编程错误
            err = fmt.Errorf("初始化失败: %v", p)
        }
    }()

    return load(), nil // 直接调用 OnceValue 返回的函数，recover 才能接住它
}

这里的转换策略要和业务约定一致。如果初始化失败意味着进程无法继续，保留 panic 让上层崩溃可能更合适；如果它只是可降级配置，则可以转换成错误并交给调用方选择默认值。不要在 recover 后无条件返回空字符串，否则会把配置缺失伪装成成功。

需要重试时，重新构造返回函数

OnceValue 没有“清空失败状态”的方法。一个已经 panic 的返回函数会继续记住同一个 panic 值，所以重试不能靠再次调用同一个变量完成。若业务确实允许重新加载，应把构造逻辑放到工厂函数中，让每次尝试获得独立的一次性状态。

func newLoader(attempts *int) func() string {
    return sync.OnceValue(func() string {
        (*attempts)++ // 每个新返回函数最多增加一次尝试次数
        if *attempts == 1 {
            panic("temporary config error") // 第一个实例固定记住这次失败
        }
        return "ready"
    })
}

attempts := 0
// 调用方应先在边界 recover，再决定是否创建新的 loader。
first := newLoader(&attempts)
second := newLoader(&attempts) // 新实例才代表新的尝试
_ = first
_ = second

更重要的设计点是：第一次 loader 的失败生命周期不会被第二次调用改变；新的 loader 才拥有新的 OnceValue 状态。并发场景下还要额外保护“谁有权创建新实例”，否则重试本身可能制造多份初始化结果。

迁移时记住这张速查表

最后可以用三个问题检查迁移是否清楚：这个初始化失败是不可恢复故障还是可降级错误？谁负责 recover，谁负责记录原始 panic？重试是否真的允许产生新的配置或连接状态？只要这三个职责已经明确，OnceValue 的“只执行一次”和“panic 可重复传播”就不会再被混为一谈。

相关问题

• OnceValue 和 OnceValues 有什么区别？前者缓存一个返回值，后者缓存两个返回值；两者对 panic 的重复传播规则一致。
• 能不能在初始化闭包内部 recover？可以，但要明确恢复后的返回值与错误语义；否则更容易把真实失败伪装成零值成功。
• OnceValue 适合所有懒加载吗？不适合需要自动重试、按租约刷新或按请求隔离的资源，这些场景需要显式生命周期管理。