sync.Once.Do无法直接返回错误，正确做法是用sync.Once+包级变量（instance/initErr）组合实现线程安全的带错单例初始化，确保错误只设一次且暴露给调用方。
Go 中 sync.Once.Do 无法直接返回错误
这是最常踩的坑：你写了个初始化函数，里面可能打开文件、连数据库、读配置，会返回 error，但 sync.Once.Do 的参数类型是 func()，不接受带返回值的函数。强行塞进去编译直接报错：cannot use func literal (type func() error) as type func() in argument to once.Do。
常见错误做法是把错误丢进全局变量或 panic，结果导致后续调用无法感知失败状态，或者 panic 后程序崩了却没人知道是初始化挂了。
- 别在
Do里直接panic—— 一旦 panic，整个 goroutine 终止，且Once状态已标记为“执行过”，后续调用不会重试，错误被静默掩盖 - 别只靠日志记录错误就完事 —— 调用方完全不知道初始化失败，可能接着用一个未初始化的单例，触发 nil pointer dereference
- 真正可行的路只有一条：把错误暴露给调用方，靠额外变量承载结果
用原子变量 + sync.Once 组合实现带错误的单例初始化
核心思路是：用 sync.Once 保证初始化函数只执行一次，用一个包级变量（比如 initErr）存错误，再用另一个变量（比如 instance）存初始化后的对象。所有对外暴露的获取函数，先检查 initErr 是否为 nil，再返回实例或错误。
示例结构：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
var (
once sync.Once
instance *Client
initErr error
)
func GetClient() (*Client, error) {
once.Do(func() {
instance, initErr = newClient() // newClient() 返回 (*Client, error)
})
return instance, initErr
}
-
newClient()里该校验配置、该连 DB 就正常写，出错直接 return error -
GetClient()每次都返回当前状态 —— 第一次调用触发初始化，之后直接返回缓存结果（含成功实例或首次失败的 error） - 注意：
instance和initErr必须是包级变量，且不能被其他地方意外修改
为什么不用 lazy.New 或第三方库？
Go 1.22+ 引入了 sync.Lazy，它的 Load() 方法确实能返回 (T, error)，看起来更干净。但实际用起来有隐性成本：
-
sync.Lazy是延迟加载，每次Load()都要走原子操作和指针判断，比sync.Once多一点开销（微乎其微，但高并发场景可测） - 它要求初始化函数必须是
func() T，仍不支持返回 error —— 你还是得自己包装一层，把 error 塞进返回值或 panic，又绕回老问题 - 很多项目还卡在 Go 1.21 或更早，
sync.Lazy直接不可用
所以除非你明确需要懒加载语义（比如初始化函数极重、且 99% 场景根本不会用到该单例），否则老老实实用 sync.Once + 双变量更可控、更易 debug。
并发安全下，错误状态必须“只设一次”
多个 goroutine 同时首次调用 GetClient() 时，sync.Once 保证只有一个执行 newClient()，其余阻塞等待。但你要确保 initErr 和 instance 的赋值是原子的、不可覆盖的 —— 尤其是错误。
- 如果
newClient()内部重试多次，某次失败后又成功，那第一次失败的initErr就不该被覆盖；但反过来，如果第一次成功，后面又有人误改了initErr，那就坏了 - 因此，赋值逻辑必须严格限定在
once.Do的回调里，且只写一次 —— 不要在回调外任何地方给initErr赋值 - 更稳妥的做法：把
initErr设为atomic.Value或直接用sync.Once控制写入，但对绝大多数场景，包级变量 + 单点写入已足够，关键是开发时守住这条线
最难缠的不是代码怎么写，而是团队里有人在 init 函数里加了 retry 逻辑，又忘了同步更新 initErr，结果单例看似初始化成功，其实用的是上一轮失败残留的 nil instance —— 这类 bug 往往要等上线压测才爆出来。
