sync.Once只能执行一次，因其用atomic.CompareAndSwapUint32原子检查done标志位，首次成功后置为1，后续调用直接返回；panic后done仍为1，不重试，需上层自行处理失败。
sync.Once 为什么只能执行一次
sync.Once 的核心是内部的 done 字段（uint32 类型）和一个互斥锁。它用 atomic.CompareAndSwapUint32 原子地判断是否已执行过，只有第一次调用 Do 且 done == 0 时才真正执行函数，并将 done 置为 1；后续所有调用都直接返回，不加锁、不阻塞、不重试。
这意味着：
- 即使传入的函数 panic，
done仍会被设为1，该Once实例从此失效 —— 不会重试，也不会再执行 - 多个 goroutine 并发调用
Do是安全的，但只有一个能真正执行函数体 -
Do接受的是func()，不能传参；需通过闭包捕获外部变量，注意变量逃逸和生命周期
典型使用场景：单例初始化与资源懒加载
最常见的不是“全局变量初始化”，而是“按需初始化昂贵资源”，比如数据库连接池、配置解析器、HTTP 客户端、日志句柄等。这些操作应满足：只做一次、线程安全、延迟到首次使用时才触发。
例如初始化一个共享的 *http.Client：
立即学习“go语言免费学习笔记（深入）”；
var (
httpClientOnce sync.Once
httpClient *http.Client
)
func GetHTTPClient() http.Client {
httpClientOnce.Do(func() {
// 这里可做 TLS 配置、超时设置、定制 Transport 等
httpClient = &http.Client{
Timeout: 30 time.Second,
}
})
return httpClient
}
注意点：
- 不要在
init()函数里用Once.Do—— 没必要，init本身已保证单次且顺序执行 - 避免在
Do函数里调用另一个Once.Do形成隐式依赖链，易引发死锁或不可预测顺序 - 若初始化逻辑可能失败（如读配置文件失败），建议在外层包装错误处理逻辑，因为
Once不提供错误回传机制
Do 函数 panic 后无法重试，怎么办
sync.Once.Do 不处理 panic：一旦函数 panic，done 仍被设为 1，后续调用直接返回，不会重新尝试。这常导致“初始化失败后永远拿不到可用实例”。
正确做法是把恢复逻辑前置，确保 Do 内部不 panic：
- 用
defer/recover捕获并记录 panic，转为返回零值或默认值 - 将可能失败的操作拆出来，先校验再执行（如检查文件是否存在、端口是否可连）
- 更推荐方式：用额外标志位 + 锁控制“失败重试”，例如定义
type lazyInit struct { once sync.Once; err error; value T }，自行封装带错误反馈的初始化逻辑
简化的带错误初始化示例：
type lazyDB struct {
once sync.Once
db *sql.DB
err error
}
func (l lazyDB) Get() (sql.DB, error) {
l.once.Do(l.init)
return l.db, l.err
}
func (l *lazyDB) init() {
db, err := sql.Open("sqlite3", "./app.db")
if err != nil {
l.err = err
return
}
l.db = db
}
Once 和 sync.OnceValue 的关键区别（Go 1.21+）
sync.OnceValue 是 Go 1.21 引入的新类型，专为“执行一次并返回一个值”设计，解决了 Once 无法直接返回结果、需靠闭包写入外部变量的问题。
它返回 any，但通常配合类型断言或泛型封装使用：
var configOnce sync.OnceValuefunc GetConfig() (Config, error) { v := configOnce.Do(func() any { cfg, err := loadConfig() if err != nil { return fmt.Errorf("load config: %w", err) } return cfg }) if err, ok := v.(error); ok { return nil, err } return v.(Config), nil }
注意：
-
OnceValue.Do返回值是any，类型安全需自己保障；生产中建议用泛型封装（如oncevalue.New(func() (T, error))） - 它同样不重试 panic，panic 时返回
nil（any(nil)），需额外判断 - 如果项目还运行在 Go OnceValue，老实用
Once+ 外部变量
最易被忽略的一点：很多人以为 Once 能替代初始化锁，其实它只保“执行一次”，不保“执行成功”——失败状态不可逆，这个边界必须由上层逻辑兜底。