OnceFunc/OnceValue 是带返回值和 panic 容错的实用方案，once.Do 仅支持无参无返回函数，需闭包写外部变量且无 panic 捕获；OnceFunc 缓存 (T, error) 结果并捕获首次 panic，OnceValue 用于纯值构造。
once.Do 是基础保障，OnceFunc/OnceValue 才是带返回值和 panic 容错的实用方案。直接用 once.Do 写单例没问题，但一旦要安全返回初始化结果、或函数可能 panic，就得换更高级的封装。
为什么 once.Do 不能直接返回值
once.Do 的签名是 func(f func())，参数必须是无参无返回值函数。这意味着你没法让它“把初始化好的 *sql.DB 返回给我”，只能靠闭包往外部变量写值——容易漏掉 nil 检查、竞态风险高、调用方还得自己判断是否已初始化。
- 必须配合包级或结构体字段使用，比如
var db *sql.DB+once.Do(func(){ db = ... }) - 如果初始化失败（比如
sql.Open报错），db会是 nil，调用方得额外判空 - 没有内置 panic 捕获，一旦
Do里 panic，后续所有调用都 panic，且无法重试
OnceFunc 和 OnceValue 怎么解决返回值问题
它们是 Go 1.21+ 引入的高级封装，自动管理 sync.Once 实例，并把初始化函数的返回值缓存下来。典型用法：
var GetDB = sync.OnceFunc(func() (*sql.DB, error) {
db, err := sql.Open("mysql", os.Getenv("DSN"))
if err != nil {
return nil, fmt.Errorf("open db: %w", err)
}
return db, nil
})
// 调用时直接拿到结果，不用管 once 或变量声明
db, err := GetDB()
-
OnceFunc适用于返回(T, error)的函数，首次调用执行并缓存结果，后续调用直接返回缓存值 -
OnceValue更轻量，只用于无 error 的纯值构造，比如OnceValue(func() time.Location { return time.LoadLocation("Asia/Shanghai") }) - 两者都会在首次调用 panic 时捕获 panic，并在后续调用中复现同一 panic，行为可预测
并发调用 once.Do 时 panic 的真实影响
这是最容易被忽略的坑：once.Do 不处理 panic，也不重置状态。只要回调函数 panic 过一次，这个 sync.Once 实例就永久失效。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 哪怕只是第一次调用时网络超时导致
http.Client初始化失败 panic，后续所有GetInstance()都会立刻 panic，而不是重试 - 修复方式只有两种：要么在闭包里用
recover拦截并转成 error 处理；要么换OnceFunc，它已内置该逻辑 - 别指望“等几秒再试一次”——
once.Do没有重试语义，它的契约就是“最多一次”，不是“至少一次”
什么时候还该坚持用原生 once.Do
不是所有场景都需要高级封装。如果你的初始化逻辑简单、确定不会 panic、且不需要返回值（比如注册全局 handler、启动后台 goroutine），once.Do 反而更清晰。
- 例如：
once.Do(func() { http.HandleFunc("/health", healthHandler) })—— 注册动作本身幂等，无返回值，也几乎不会 panic - 或者初始化一个只读配置 map，且确保构造过程绝对稳定
- 注意：多个独立资源不要共用同一个
sync.Once实例，它们之间不共享状态，也不能靠它协调顺序
真正关键的不是选哪个 API，而是想清楚初始化失败后你希望程序怎么反应：静默失败？返回 error？还是 panic 并终止？once.Do 把选择权全交给你，OnceFunc 则默认走 error 分支——这个差异，在上线前压测时最容易暴露出来。
