sync.Once 是 Go 实现单例最可靠的方式，底层用原子操作+状态机实现，支持懒加载、并发安全、带参初始化；需注意 Do() 不返回值、panic 后不重试、once 必须为包级变量。
sync.Once 是 Go 单例最可靠的选择
不用自己加锁、不用判断 nil、不用写双重检查，sync.Once 就是 Go 官方为“只执行一次”这个需求量身定制的工具。它底层用原子操作 + 状态机实现，比手写 sync.Mutex 更轻量、更安全，也比用 init() 更灵活（支持带参数初始化）。
常见错误是试图在 sync.Once.Do() 里返回值——它签名是 func(f func())，不接受返回值。所以单例对象得提前声明变量，在闭包里赋值。
- 必须用指针或全局变量承接初始化结果，比如
var instance *DB -
sync.Once本身不是线程安全的？错。它自己就是并发安全的，但你要保证传给Do()的函数内部逻辑也安全（比如里面别又去读写未保护的全局变量） - 如果初始化函数 panic，
sync.Once会认为“已执行”，后续调用不再尝试——这是设计行为，不是 bug
标准单例写法：懒加载 + 并发安全
典型场景是数据库连接、配置加载、日志实例等需要延迟初始化且全局唯一的服务。关键点在于把创建逻辑包裹进 Do()，并用闭包捕获外部变量。
var (
instance *Config
once sync.Once
)
func GetConfig() *Config {
once.Do(func() {
instance = &Config{Path: "/etc/app.yaml"}
// 这里可做文件读取、解析、校验等耗时操作
})
return instance
}
注意：once 必须是包级变量（不能每次调用都 new 一个），否则每个 goroutine 都有自己的 sync.Once，完全失去意义。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 不要在多个地方定义独立的
sync.Once变量来控制同一个资源 - 如果初始化需要参数（比如环境名），建议封装成函数工厂：
func NewConfig(env string) *Config，再在Do()里调用 - 避免在
Do()闭包里引用可能被修改的局部变量（尤其是循环变量），容易产生意料外的值
sync.Once.Do() panic 后无法重试，得手动兜底
这是最容易被忽略的坑：一旦初始化函数 panic，sync.Once 内部状态变成 done，后续所有 Do() 调用直接返回，不会再尝试初始化。此时 instance 可能还是 nil，导致运行时 panic。
真实错误现象：panic: runtime error: invalid memory address or nil pointer dereference，但堆栈里看不到初始化失败的线索。
- 初始化前加日志，比如
log.Println("initializing config...") - 初始化后做基础校验，例如
if instance == nil { panic("config init failed") } - 更稳妥的做法是把初始化逻辑拆成两步：先准备数据（不 panic），再原子赋值；或者用返回错误的方式替代 panic
性能和兼容性：几乎没有代价，Go 1.0+ 全支持
sync.Once 在首次调用后几乎无开销——后续只是读一个 int32 原子变量。它的内存占用极小（16 字节），比任何基于 mutex 的方案都快。Go 1.0 就已存在，无需担心版本兼容问题。
但要注意：它只保证“执行一次”，不保证“初始化完成前阻塞其他 goroutine”。也就是说，A goroutine 进入 Do() 开始初始化，B goroutine 此时调用 Do() 会阻塞，直到 A 完成；但如果 B 拿到的是尚未初始化完成的指针（比如结构体字段还没填完），而你又没做同步，就可能读到脏数据。
- 确保初始化函数是原子的：要么全做完，要么不暴露中间态（比如先构造好对象，再一次性赋值给全局变量）
- 不要在初始化函数里启动 goroutine 并异步写全局变量——这破坏了
sync.Once的语义 - 如果初始化过程特别长（如拉远程配置），考虑加超时或健康检查，而不是依赖
sync.Once自身
