Go中唯一推荐的单例实现是sync.Once+包级指针变量,因其线程安全、延迟初始化、支持错误返回;禁用if-nil判断(易竞态)、init()(无法按需/返错/测试)及局部声明once(失效)。

用 sync.Once + 包级指针变量,是 Go 里唯一值得推荐的单例实现方式。其他写法要么线程不安全,要么无法返回错误,要么破坏测试可替换性——不是“不够优雅”,而是根本不可靠。
为什么不能用 if instance == nil 手动判断
看似简单,实则危险:多个 goroutine 同时进入 GetXXX() 时,可能都看到 instance == nil,然后各自执行初始化,最终创建多个实例。Go 内存模型不保证写操作对其他 goroutine 的立即可见,即使加了锁,若没做 double-check 或没用原子同步,仍可能返回未完全构造的对象。
- 典型错误现象:
nil pointer dereference或数据库连接被重复dial - 它不处理竞态,也不提供 happens-before 语义
- 哪怕加了
sync.Mutex,也容易漏掉锁内二次判空,或初始化中途 panic 导致状态不一致
sync.Once 必须是包级或结构体字段,不能局部声明
sync.Once 的作用是“标记某段逻辑只执行一次”,如果把它放在函数内部,每次调用都会新建一个,彻底失去意义。
- 包级声明正确:
var once sync.Once(在变量声明块中) - 结构体内嵌也行:
type Client struct { once sync.Once; db *sql.DB },但方法必须用指针接收者 - ❌ 错误写法:
func GetDB() *DB { once := new(sync.Once); once.Do(...) }—— 每次都是新once,永远不生效
初始化失败怎么办?必须显式返回 error
像数据库连接、配置加载这类操作,失败是常态。sync.Once 不会重试,但它会把 panic 或正常返回都记为“已完成”。所以失败状态必须由你主动捕获并暴露。
- 用两个包级变量:
instance *DB和err error - 在
once.Do闭包里完成全部初始化逻辑,并统一赋值instance和err - 调用方必须检查
err,不能忽略;GetInstance()返回(*T, error)是标准做法 - ⚠️ 注意:
sync.Once记住的是“执行过”,不是“成功过”。一旦初始化 panic,后续调用直接返回缓存的nil, err,不会重试
别碰 init() 做单例初始化
init() 在包加载时运行,时机不可控,且签名固定不能返回 error。它适合预编译正则、注册编码器这类纯内存、无副作用的操作。
- 常见踩坑:在
init()里调用sql.Open()或读取os.Getenv()—— 此时flag.Parse()可能还没执行,环境变量为空,直接 panic - 测试时无法重置:单例已在测试启动前固化,mock 无从下手
- 依赖顺序难管理:A 包
init()依赖 B 包的配置,但导入路径决定执行顺序,极易出错
真正麻烦的点不在写法本身,而在于初始化函数里的副作用是否可逆——比如发了一次 HTTP 请求、写了一个临时文件,一旦失败,sync.Once 就把它“钉死”了。这种场景下,单例不该承担重试或恢复逻辑,而应由上层控制生命周期,或者干脆放弃单例,改用显式构造 + 依赖注入。


















