sync.Once 通过内部状态机确保初始化函数只执行一次。它使用一个布尔标志和一个互斥锁来跟踪是否已执行过该函数。第一次调用 Do 方法时，会获取锁并执行函数，之后的调用会直接返回，不再执行。这种方式可以有效避免竞态条件，确保初始化操作的原子性和唯一性。

sync.Once 是 Go 中轻量高效的单次初始化原语，通过无锁的原子状态判断（uint32 done + atomic.CompareAndSwapUint32）实现高并发下的快速分流——绝大多数 goroutine 根本不进锁，仅首次调用会加锁执行并不可逆地标记完成；但它绝非“错误处理工具”：panic 不被拦截、失败不重试、结果不保证，一旦触发即永久关闭，因此必须谨慎设计初始化逻辑（如手动 recover 并暴露错误）、避免误用多个实例或在函数内声明，并明确其适用边界——只适合确定性、幂等、轻量的初始化，复杂场景应转向 singleflight 或显式生命周期管理。

sync.Once.Do 只保证「同一个实例」上最多执行一次传入函数，不保证成功、不自动重试、也不处理 panic 传播——它只管“是否已调用过”，不管“调用结果如何”。

sync.Once.Do 的原子状态判断机制

内部靠一个 uint32 类型的 done 字段 + atomic.CompareAndSwapUint32 实现无锁快速判断。首次调用时，若 done == 0，就加锁执行函数并原子写入 1；后续所有调用都直接跳过函数体。

• 不是靠互斥锁拦住所有并发调用，而是靠原子读快速分流：绝大多数 goroutine 根本不进锁路径
• 一旦 atomic.StoreUint32(&o.done, 1) 执行完成，状态不可逆，哪怕函数 panic 也再不会重试
• 这个设计让 Do 在高并发下依然轻量，但代价是“失败即终局”

为什么多次调用 Do 还会重复执行？

常见原因是用了多个独立的 sync.Once 实例，而不是复用同一个。每个实例的 done 状态完全隔离。

• 在函数内声明：func handler() { var once sync.Once; once.Do(...) } → 每次都新建，每次都执行
• 作为 struct 值字段：type S struct { once sync.Once } → 每次 new(S) 都得到新状态，毫无意义
• 正确做法：包级变量 var once sync.Once，或结构体中存指针 once *sync.Once 并初始化为 new(sync.Once)

panic 后的 Do 行为容易被误判

如果传给 Do 的函数 panic，sync.Once 仍会把 done 设为 1，后续调用直接返回，不再执行函数——但 panic 不会被 recover，会继续向上抛出。

• 现象：第一次调用 panic，第二次调用直接返回（看似“没再执行”），但实际单例对象仍是零值或半初始化状态
• 错误应对：指望 “panic 后自动重试” 或 “Once 自动吞掉错误” —— 它不做这些
• 正确做法：在闭包内手动 defer func() { recover() }()，并把错误记录到共享变量（如 err error），供调用方检查

sync.Once 不适合带参数或需重试的初始化

Do 只接受 func()，无法传参；且失败后不重试。这两点决定了它只适合“确定性、幂等、轻量”的初始化逻辑。

• 需要参数？别塞闭包捕获局部变量（易内存泄漏/竞态），改用显式构造函数：NewService(cfg Config)，再由上层控制单例生命周期
• 可能失败需重试？sync.Once 不是解决方案，应改用 singleflight.Group 或自定义带错误回退的懒加载封装
• 初始化耗时长（如连 DB、拉配置）？别等到首次请求才触发，提前在 main() 中调用一次 Do，避免首请求阻塞

最常被忽略的一点：sync.Once 是个“开关”，不是“保险丝”。它关上就永远关着，不管里面通没通电。

好了，本文到此结束，带大家了解了《sync.Once 通过内部状态机确保初始化函数只执行一次。它使用一个布尔标志和一个互斥锁来跟踪是否已执行过该函数。第一次调用 Do 方法时，会获取锁并执行函数，之后的调用会直接返回，不再执行。这种方式可以有效避免竞态条件，确保初始化操作的原子性和唯一性。》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！