sync.once 是懒汉单例最稳妥的选择，因其专为“只执行一次”设计，采用原子操作+互斥锁双保险，自动处理 panic 恢复，避免重复初始化与状态污染，且性能优异。
为什么 sync.Once 是懒汉单例最稳妥的选择
因为它是 Go 标准库里唯一专为「只执行一次」设计的并发原语，底层用原子操作 + 互斥锁双保险，既避免重复初始化，又不会像自己手写 sync.Mutex 那样漏掉双重检查或忘记 unlock。
常见错误现象：if instance == nil { mu.Lock(); if instance == nil { instance = newThing() } mu.Unlock() } —— 看似双重检查，但一旦 newThing() panic，instance 就永远卡在 nil，后续调用全阻塞。
使用场景：全局配置加载、数据库连接池初始化、第三方 SDK 客户端首次构建。
-
sync.Once的Do方法内部已处理 panic 恢复，失败后不会重试，也不会污染状态 - 它不关心你传进去的函数是否带参数，只保证该函数在整个程序生命周期内最多执行一次
- 性能上几乎没有额外开销：未执行过时是纯原子读，执行中才加锁，执行完回归原子读
sync.Once 单例写法模板与关键细节
不是套个 Once.Do 就万事大吉，初始化逻辑的位置和变量作用域决定是否真线程安全。
立即学习“go语言免费学习笔记（深入）”；
典型错误写法：var once sync.Once; func GetInstance() *Client { var client *Client; once.Do(func(){ client = &Client{} }); return client } —— client 是局部变量，每次调用都新建，once 完全没起作用。
正确结构必须把实例变量提到包级或全局作用域：
var (
instance *Config
once sync.Once
)
func GetConfig() *Config {
once.Do(func() {
instance = &Config{...}
// 这里可做 I/O 或复杂初始化
})
return instance
}
- 必须用包级变量存实例，不能在
Do闭包里声明新变量再赋值给局部变量 -
once变量本身也建议包级声明，否则每次调用都 new 一个sync.Once，完全失效 - 如果初始化函数需要返回 error，得自己包装一层（
sync.Once不支持），比如用sync.OnceValue（Go 1.21+）或额外加err包级变量
Go 1.21+ 的 sync.OnceValue 能替代吗
能，而且更干净——它直接返回初始化结果，还天然支持 error 传播，但要注意兼容性和语义差异。
常见误用：val := sync.OnceValue(func() any { return initDB() })，然后每次调用 val.Load() —— 错！OnceValue 是值，不是控制流开关，必须包级声明并复用同一个实例。
使用场景：你想让初始化函数有返回值且不想自己管理 error 变量时，比手写 sync.Once + err 包级变量更少出错。
-
OnceValue初始化函数返回any，需显式类型断言（如v.Load().(*DB)），不如Once直接赋值直观 - Go 1.20 及以下无法用，老项目升级前得确认版本
- 它不捕获 panic，panic 会向上传播；而
sync.Once.Do会 recover 并静默失败（这点反而有时更稳）
容易被忽略的「销毁」和「重置」问题
sync.Once 和 sync.OnceValue 都不可重置——一旦执行过，就永远标记为“已完成”。没有 Reset 方法，也没必要有。
这意味着：单元测试里如果单例依赖外部状态（比如 mock HTTP server），多次运行测试会因单例已初始化而失败。
- 测试时要么用
init函数隔离，要么把单例逻辑抽成可注入的 factory 函数，测试时传入不同实现 - 不要试图用
unsafe或反射去清空sync.Once内部字段，Go 不保证其内存布局，下个版本可能崩溃 - 真正需要“重置”的场景，往往说明设计上不该用单例，而是该用依赖注入或 context 生命周期管理
懒汉单例真正的难点从来不在“怎么写”，而在于“什么时候不该写”——一旦实例持有资源或状态，它的生命周期就脱离了调用方控制。
