sync.Once.Do的原子性靠uint32原子变量done与两次原子操作实现:先atomic.LoadUint32检查,再atomic.CompareAndSwapUint32争抢执行权,仅CAS成功者执行函数,其余goroutine阻塞等待结果,全程无竞态。

sync.Once.Do 的原子性靠什么实现
靠一个 uint32 原子变量 + 两次原子读写,不是靠锁全程保护。第一次调用时,它先用 atomic.LoadUint32 检查 done 是否为 0;如果是,再用 atomic.CompareAndSwapUint32 尝试把 0 → 1;只有 CAS 成功的那个 goroutine 才真正执行函数,其余全部阻塞在互斥锁上等待——但不会重复执行。
这意味着:它不是“谁先到谁执行”,而是“谁抢到 CAS 谁执行”,其余人纯等待结果。整个过程没有竞态窗口,也不依赖外部同步逻辑。
为什么多次调用 Do 还会执行多次
最常见原因是用了多个独立的 sync.Once 实例。每个实例的 done 状态互不干扰,哪怕它们调用的是同一个初始化函数。
- 函数内声明:
func initDB() { var once sync.Once; once.Do(...) }→ 每次都新建,每次都会执行 - struct 值字段:
type Client struct { once sync.Once }→ 每次new(Client)都有新状态,毫无意义 - map 或 slice 中存值:
m["key"] = sync.Once{}→ 复制后状态丢失,等价于新建
正确做法只有两个:包级变量(var once sync.Once),或结构体中存指针(once *sync.Once,初始化为 new(sync.Once))。
立即学习“go语言免费学习笔记(深入)”;
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
panic 会导致初始化失败却“被标记为完成”
sync.Once 不捕获 panic。一旦传入的函数 panic,done 仍会被设为 1,后续所有 Do 调用直接返回,不再重试,也不通知调用方失败。
- 后果是:程序可能卡在未初始化状态,但你完全感知不到
- 不能靠
log.Fatal或os.Exit终止流程,否则等待中的 goroutine 永远卡住,造成泄漏 - 必须在闭包内手动
defer/recover,并把错误显式存到共享变量(如包级initErr error)供后续检查
例如:once.Do(func() { if err := loadConfig(); err != nil { initErr = err; return } ... }),之后调用方需主动检查 initErr。
Do 接收的函数不能带参数,闭包捕获要小心
sync.Once.Do 签名固定为 func(f func()),无法传参。常见错误是闭包引用了循环变量或外部可变变量:
- 错误:
for i := 0; i → 全部输出 <code>3 - 错误:
once.Do(func() { init(path) }),而path后续被修改 → 闭包捕获的是变量地址,不是快照 - 正确:
pathCopy := path; once.Do(func() { init(pathCopy) })或用立即执行函数传参
这也意味着:需要按 key 初始化不同资源时,sync.Once 本身不适用,得换 sync.Map 或 map 加锁控制。
最易被忽略的一点是:sync.Once 的零值有效,但只要它被复制(值传递、结构体字段拷贝、map 存值),就等于放弃所有保证——它的安全性完全依赖生命周期和唯一性,而不是语法或类型系统能约束的。

















