go 中确保初始化逻辑只执行一次且线程安全应使用 sync.once，而非包级变量或 init() 函数；后者无法控制时机、无错误处理、不可重试，而 sync.once 支持按需触发、懒加载，但不可重置，失败后需重启或手动实现带重试的惰性加载。
Go 语言本身没有“单次执行模块”这个内置概念，但你实际想解决的，是「如何确保某段初始化逻辑（比如配置加载、数据库连接池初始化、全局状态注册）只运行一次，且线程安全」——这在 Go 中靠 sync.Once 实现，不是靠模块机制。
为什么不能靠包级变量或 init() 函数实现“单次执行”
包级变量赋值和 init() 函数确实只执行一次，但它们发生在包导入时，无法控制时机，也无法传参、捕获错误、重试或延迟触发。一旦出错（比如配置文件缺失），整个程序启动失败，且无法二次调用修复。
-
init()在main()之前强制运行，不可跳过、不可重试 - 包级变量初始化表达式同样无错误处理能力，panic 会直接终止进程
- 多个包相互 import 时，
init()执行顺序由依赖图决定，不可控
用 sync.Once 封装可按需触发的单次逻辑
sync.Once 是 Go 标准库提供的轻量级同步原语，它保证内部函数最多执行一次，且后续调用立即返回，不阻塞。适合封装需要“首次访问才初始化”的场景，比如：
- 懒加载配置解析器（避免启动时读取失败导致 crash）
- 按需初始化 HTTP 客户端或数据库连接池
- 注册全局指标（Prometheus）或信号处理器
示例：
var (
once sync.Once
cfg *Config
err error
)
func GetConfig() (*Config, error) {
once.Do(func() {
cfg, err = loadConfigFromEnv()
})
return cfg, err
}
注意：必须把 cfg 和 err 声明为包级变量，否则每次调用都新建局部变量，once.Do 失效。
常见误用：把 sync.Once 当成“单例构造器”滥用
很多人试图用 sync.Once 包裹 new 或 &Struct{} 来实现单例对象，但这只是“单次构造”，不等于“单例模式”。真正要注意的是：
- 如果构造函数返回指针，要确保该指针所指向的对象状态是线程安全的（比如内部字段是否加锁）
- 不要在
once.Do里做耗时操作（如远程 HTTP 请求），否则首次调用会卡住所有 goroutine - 无法重置
sync.Once—— 一旦执行过，就永远不能再触发，出错后只能重启进程
替代方案：带错误重试的惰性初始化（需要手动控制）
如果你需要“失败后允许重试”，sync.Once 不适用。此时应自己维护状态变量：
type lazyLoader struct {
mu sync.RWMutex
loaded bool
cfg *Config
lastErr error
}
func (l *lazyLoader) Load() (*Config, error) {
l.mu.RLock()
if l.loaded && l.lastErr == nil {
defer l.mu.RUnlock()
return l.cfg, nil
}
l.mu.RUnlock()
l.mu.Lock()
defer l.mu.Unlock()
if l.loaded {
return l.cfg, l.lastErr
}
l.cfg, l.lastErr = loadConfigFromEnv()
l.loaded = true
return l.cfg, l.lastErr
}
这种写法牺牲了 sync.Once 的简洁性，但换来可控性 —— 比如可以加 time.Sleep 后重试，或配合 context 超时控制。
真正容易被忽略的是：单次执行 ≠ 单例对象。很多问题本质是“首次初始化失败怎么恢复”，而不是“怎么只跑一次”。别让 sync.Once 成为掩盖设计缺陷的胶带。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
