Golang sync.Once实现线程安全单例

为什么 sync.Once 比 if + mutex 更适合单例初始化

因为 sync.Once 保证 Do 中的函数只执行一次，且天然阻塞后续 goroutine 直到初始化完成，避免了「双重检查锁定」里常见的内存重排序问题。而手写 if + sync.Mutex 容易漏掉对 initDone 标志的 volatile 语义保障（Go 中虽有 happens-before 规则，但手动实现仍易出错）。

常见错误现象：nil pointer dereference 或多个 goroutine 同时进入初始化逻辑，导致资源重复创建甚至 panic。

• 必须把初始化逻辑完整封装进 Once.Do 的函数参数中，不能拆成「判断 → 加锁 → 再判断 → 初始化」
• sync.Once 不可重用：一旦 Do 返回，其内部状态不可重置
• 初始化函数若 panic，Once.Do 会传播 panic，且该 Once 视为已执行 —— 后续调用仍 panic，不会重试

标准单例结构：带 error 的懒加载模式

实际项目中初始化常可能失败（比如打开配置文件、连接数据库），所以单例构造函数应返回 (*T, error)，并缓存 error 结果。不能只靠 sync.Once 管理指针，还要管理初始化结果状态。

典型结构是用闭包捕获首次调用的返回值，并通过指针或全局变量暴露实例：

var (
    instance *Config
    once     sync.Once
    initErr  error
)

type Config struct {
    Port int
    Host string
}

func GetConfig() (*Config, error) {
    once.Do(func() {
        instance, initErr = loadConfig()
    })
    return instance, initErr
}

func loadConfig() (*Config, error) {
    // 模拟可能失败的初始化
    return &Config{Port: 8080, Host: "localhost"}, nil
}

sync.Once.Do 传参陷阱：别在闭包里捕获未初始化变量

如果在 once.Do 外提前声明变量但未赋值，又在闭包中直接使用，会导致竞态或零值被返回。Go 编译器不会报错，但行为不可控。

• 错误写法：var conf *Config; once.Do(func() { conf = new(Config) }) —— 若 conf 是包级变量，其他 goroutine 可能在 Do 完成前读到 nil
• 正确做法：始终用一个「结果变量」承接初始化输出（如上例中的 instance 和 initErr），并在 Do 外不暴露未就绪状态
• 不要试图在 Do 闭包里修改外部作用域的 map/slice 元素来“间接初始化”，这无法保证可见性

替代方案对比：sync.Once vs. init 函数 vs. 饿汉式

init 函数是编译期确定的、无条件执行的，适合纯静态配置；饿汉式（包加载时直接初始化）无法处理依赖外部 I/O 的场景；而 sync.Once 是唯一支持「按需、一次、线程安全、可失败」初始化的机制。

• init()：无法返回 error，无法延迟，无法按需触发
• 饿汉式：var instance = NewExpensiveService() —— 若 NewExpensiveService() panic，整个包加载失败，且无法做错误恢复
• sync.Once：明确分离「定义」和「执行」，调用方控制时机，失败可透出、可记录、可重试（由上层决定）

真正容易被忽略的是：一旦 sync.Once.Do 中的函数 panic，这个 Once 就永久失效了 —— 即使你修复了 panic 原因，后续调用也不会再执行初始化逻辑。调试时要特别注意日志是否只出现一次 panic 输出。