sync.Once.Do 中函数 panic 后会持续失败，因不标记完成且不捕获 panic；须在闭包内 defer/recover 或改用 error 返回路径，并确保 once 为包级变量、显式赋值实例与错误变量。
sync.Once.Do 传入函数 panic 后永远失败
一旦 Do 里执行的函数 panic，sync.Once 不会标记为“已完成”，也不会捕获或重试——后续所有调用都会再次进入该函数，再次 panic。这不是 bug，是设计使然：它只保证“执行一次”，不保证“成功一次”。
常见错误是直接在 Do 里调用可能失败的外部操作，比如 sql.Open、os.ReadFile 或 HTTP 请求。一旦出错，整个单例不可用，且无提示。
- 必须在闭包内用
defer/recover捕获 panic，或改用显式 error 返回路径 - 推荐把初始化逻辑单独抽成函数（如
newDB(dsn string) (*sql.DB, error)），在Do中调用并处理错误 - 不要依赖
sync.Once自动兜底；错误传播靠你自己的变量（如dbErr error）和返回值
包级 sync.Once 声明位置错误导致失效
sync.Once 必须是包级变量或结构体字段，绝不能是函数局部变量。否则每次调用 GetInstance() 都新建一个 Once 实例，完全失去“只执行一次”的意义。
典型误写：
func GetInstance() *Service {
var once sync.Once // ❌ 局部声明，每次都是新实例
once.Do(func() { /* ... */ })
}
正确做法是声明在文件顶部，与实例变量同级：
var (
instance *Service
once sync.Once
)
- 结构体内嵌
sync.Once是可行的，但方法接收者必须是指针类型（func (s *Service) Init()），否则每次调用都操作副本 - 多个单例之间有依赖时（A 初始化需先调用
GetB()），双方的once都必须是包级变量，且依赖方要在Do内显式触发被依赖方的初始化 - 避免循环依赖：A 的
Do调 B，B 的Do又调 A —— 会死锁，Go 不报错，运行时卡住
初始化函数返回值被忽略，实例可能为 nil
sync.Once.Do 的参数类型是 func()，无法返回值。所以必须在闭包内显式赋值给包级变量（如 instance = &Service{}），否则调用方拿到的是零值指针。
危险写法：
func GetInstance() *Service {
once.Do(func() {
return &Service{} // ❌ return 无效，instance 未赋值
})
return instance // 可能为 nil
}
正确结构必须包含三要素：包级指针变量 + 包级 sync.Once + 闭包内赋值：
var (
instance *Service
once sync.Once
)
<p>func GetInstance() *Service {
once.Do(func() {
instance = &Service{} // ✅ 显式赋值
})
return instance
}
</p>
- 如果初始化可能失败，务必配套声明错误变量（如
err error），并在Do中一起赋值 - 不要把
instance声明为值类型（如var instance Service），大结构体复制开销高，且指针语义更符合单例本意 - 对外暴露的获取函数（如
GetInstance()）应返回指针或接口，避免调用方误以为可安全拷贝
与 init() 混用引发时机混乱和测试困难
把需要延迟加载的资源（如 DB 连接、配置解析）塞进 init()，会导致启动即失败、无法重试、不可 mock，且依赖顺序不可控。
反例：
func init() {
db, _ = sql.Open("mysql", os.Getenv("DSN")) // ❌ 启动就连，失败则 panic
}
正确策略是明确分工：
-
init()只做无副作用、确定成功的事：注册编解码器、预设常量映射、初始化空缓存等 - 带 I/O、网络、环境依赖的初始化，一律交给
sync.Once+ 显式获取函数（如GetDB()） - 测试时，可通过直接调用构造函数（如
NewService(cfg)）绕过全局状态，避免 test 文件 import 即触发初始化
大型项目里最易被忽略的一点：单例初始化函数若隐式依赖其他包的全局变量（比如某个中间件的配置包尚未完成 init），而你又没在 Do 里加校验，结果就是静默失败或 panic —— 这类问题在线上很难复现，只能靠初始化函数内部做防御性检查。
