Go单例不能仅靠包级变量实现，因并发下易出现竞态；必须用sync.Once延迟初始化并保证线程安全，且带错误返回的初始化需在Do内捕获错误。
为什么 Go 的单例不能靠包级变量硬写
包级变量 var instance *Singleton 看似简单，但并发调用时可能生成多个实例。Go 运行时不会自动保证包初始化阶段的线程安全，尤其当 init() 里有耗时操作或依赖外部状态时，极易出现竞态——go run -race 一跑就报 data race。
- 不要在
init()中直接 new 实例，除非它完全无状态、无副作用 - 包级变量必须配合
sync.Once延迟初始化，否则不是单例，是“伪单例” - 导出的变量（如
Instance）若没加锁读取，仍可能返回 nil 或未完成初始化的指针
标准做法：sync.Once + 指针返回
这是 Go 官方文档推荐、生产环境最稳妥的方式。核心是把初始化逻辑封进一个函数，由 sync.Once.Do() 保证只执行一次，且自带互斥语义。
package singleton
import "sync"
type Singleton struct {
name string
}
var (
instance *Singleton
once sync.Once
)
func GetInstance(name string) *Singleton {
once.Do(func() {
instance = &Singleton{name: name}
})
return instance
}
-
once.Do()内部使用原子操作和互斥锁，比手写sync.Mutex更轻量、更可靠 - 函数参数（如
name）只能在首次调用时生效；后续调用传参会被忽略——这是设计使然，不是 bug - 如果需要支持运行时重置（极少见），得额外加锁控制
once和instance，但会破坏单例语义
带错误返回的单例初始化
真实场景中，单例常需加载配置、连数据库、读文件，这些操作可能失败。此时不能把错误吞掉，也不能让 GetInstance() 返回 nil 而不告知原因。
package singleton
import (
"errors"
"sync"
)
type ConfigurableSingleton struct {
config map[string]string
}
var (
configInstance *ConfigurableSingleton
configOnce sync.O
nce
configErr error
)
func NewConfigurableSingleton(cfg map[string]string) (*ConfigurableSingleton, error) {
if len(cfg) == 0 {
return nil, errors.New("config cannot be empty")
}
return &ConfigurableSingleton{config: cfg}, nil
}
func GetConfigInstance(cfg map[string]string) (*ConfigurableSingleton, error) {
configOnce.Do(func() {
configInstance, configErr = NewConfigurableSingleton(cfg)
})
return configInstance, configErr
}
- 错误必须在
Do内捕获并保存，否则多次调用会反复尝试失败操作 - 不能把
error放进结构体字段——那属于实例状态，不是初始化结果 - 如果初始化失败，后续所有
GetConfigInstance()都返回同一错误，符合预期
测试时如何替换单例依赖
单元测试中，你无法重置 sync.Once，也不能改写已导出的全局变量（Go 不允许赋值给包级导出变量）。硬测单例会导致测试间污染。
- 对外暴露可注入的接口变量，比如
var Instance Interface = &realImpl{}，测试时直接赋值新实现 - 用函数变量替代结构体变量：
var NewSingleton = func() *Singleton { return &Singleton{} }，测试时重写该函数 - 绝对不要在测试里用
reflect强制修改私有字段——脆弱、不可维护、绕过类型系统
单例真正的难点不在写法，而在边界控制：什么时候该用，什么时候该拆成依赖注入。初始化逻辑越重，越要警惕它成为启动瓶颈或测试障碍。
