Go 的 sync.Once 是单例初始化首选，因其线程安全、无反射开销、自动处理双重检查锁；需配合错误返回、指针类型包变量及懒加载实现，避免并发初始化或忽略失败。
为什么 Go 的 sync.Once 是单例初始
化的首选
化的首选Go 没有类和构造函数，所谓“单例”本质是全局唯一实例 + 一次初始化。直接用包级变量加 sync.Once 是最简洁、线程安全且无反射开销的方式。不用 init() 是因为它无法捕获错误；不用双重检查锁（DCL）是因为 Go 的 sync.Once 已经高效封装了该逻辑，手动实现反而容易出错。
常见错误：在多个 goroutine 中并发调用未加保护的初始化函数，导致多次实例化或 panic；或误用 new() / &T{} 直接赋值包变量，绕过初始化逻辑。
-
sync.Once保证Do()中的函数只执行一次，即使多个 goroutine 同时调用 - 初始化函数应返回实例和 error，便于上层处理失败情况
- 包变量声明为指针类型（如
*Config），避免值拷贝破坏单例语义
标准单例结构：带错误处理的懒加载实现
典型场景是配置加载、数据库连接池、日志器等需延迟初始化且全局复用的资源。必须支持初始化失败回退，不能静默忽略错误。
package singleton
import (
"sync"
)
type Config struct {
Host string
Port int
}
var (
configInstance *Config
configOnce sync.Once
configErr error
)
func GetConfig() (*Config, error) {
configOnce.Do(func() {
// 模拟可能失败的初始化逻辑
c := &Config{Host: "localhost", Port: 8080}
// 假设这里校验 Port 是否合法
if c.Port <= 0 {
configErr = &ConfigError{"invalid port"}
return
}
configInstance = c
})
return configInstance, configErr
}
type ConfigError struct {
msg string
}
func (e *ConfigError) Error() string { return e.msg }
注意：configOnce.Do() 内部不抛 panic，而是通过闭包外的 configErr 传出错误；调用方必须检查返回的 error，不能只判空指针。
避免全局变量污染：用结构体方法封装单例行为
当单例需要多种初始化策略（如从文件、环境变量、默认值），或需支持测试时替换依赖，把单例逻辑收进结构体更可控。此时“单例”不再是包级变量，而是由使用者显式创建并传递的唯一实例。
常见误区：把 sync.Once 放在结构体字段里，却让多个结构体实例共享同一个 Once —— 这违反单例本意；或者在方法里每次都 new 一个新 sync.Once，失去同步效果。
- 将
sync.Once和实例字段放在同一结构体内，确保生命周期一致 - 提供 NewXXX() 函数统一创建，禁止外部直接 &T{} 构造
- 测试时可通过 NewXXXWithConfig() 接受 mock 参数，绕过真实初始化
并发安全陷阱：不要在单例内部暴露可变状态
单例对象本身线程安全 ≠ 其字段线程安全。例如 map 或切片若被多个 goroutine 读写，仍会 panic。
典型错误：单例中定义 cache map[string]string，然后在 Get() / Set() 方法中直接操作，没加锁或用 sync.Map。
- 优先使用不可变字段（如 string、int、struct 值类型）
- 若需可变状态，用
sync.RWMutex保护读写，或改用sync.Map（适用于读多写少） - 避免在单例方法中启动 goroutine 并修改其字段 —— 容易引发竞态，go test -race 会报错
真正难的不是写出来，而是想清楚哪些状态必须全局唯一、哪些只是方便复用；还有就是——初始化失败时，你的调用方真的会检查 error 吗？
