必须用包级 sync.Once 配合结构体封装结果和错误返回，否则易返回 nil 或静默失败；Do 内 panic 不被捕获、不能重试、无 error 透出；初始化不可阻塞，需提前在 main 中触发。
直接结论：用 sync.Once 实现线程安全单例，必须搭配包级变量 + 显式赋值 + 错误封装，否则极易返回 nil 或静默失败。
为什么不能只写 once.Do(func() { instance = &Service{} })
这种写法看似简洁，但实际埋了三个雷：
- 如果
&Service{}构造函数内部 panic（比如配置缺失、DB 连接超时），instance保持零值，后续调用GetInstance()直接返回nil，调用方无感知 -
sync.Once.Do不捕获 panic，也不重试 —— 它只标记“已执行”，不管成功与否 - 没有 error 透出路径，上层无法区分“还没初始化”和“初始化失败”，日志里只看到空指针 panic，排查困难
sync.Once 必须声明为包级变量，且不能放进 struct
常见误用是把 sync.Once 当作 struct 字段或函数内局部变量：
-
func handler() { var once sync.Once; once.Do(...) }→ 每次请求都新建once，完全失去“一次”语义 -
type S struct { once sync.Once }→ 每次new(S)都得到全新状态，多个实例各自初始化 - 测试中复用全局
sync.Once→ 第一个 test case 执行后，后续全部跳过，mock 失效
正确做法：在包顶层声明 var serviceOnce sync.Once，确保所有 goroutine 共享同一个实例。
立即学习“go语言免费学习笔记（深入）”；
带错误返回的单例必须用结构体封装结果
sync.Once.Do 的函数签名是 func()，没法返回 error。硬塞 log.Fatal 或 panic 会让服务启动失败不可控。可靠方案是：
- 定义私有结构体：
var serviceInst struct{ instance *Service; err error } - 在
Do内完整执行并赋值：serviceInst = struct{...}{instance: s, err: err} - 对外函数签名必须是
func GetService() (*Service, error)，不能省略error - 避免拆成两个独立包级变量（如
var instance *Service和var err error），否则并发读写可能读到不一致状态
别让首次请求卡在 sync.Once.Do 里等耗时操作
sync.Once.Do 是同步阻塞的。如果初始化逻辑包含无 timeout 的 HTTP 请求、未设 deadline 的 DB dial 或大文件加载，所有首个调用它的 goroutine 都会卡住 —— HTTP handler 可能直接超时。
- 不要等到第一个 API 请求才触发初始化；应在
main()开头主动调用一次GetService() - 初始化函数内禁止做长耗时操作；如有必要，应提前设好 timeout / deadline，并在失败时明确返回 error
- 若初始化依赖远程配置中心，建议先本地 fallback，再异步刷新，而非阻塞等待
最易被忽略的点：sync.Once 本身不解决初始化失败问题，它只解决“重复执行”问题。是否可用、是否就绪、是否可重试，全靠你封装的初始化逻辑兜底。
