正确做法是用 sync.Once 包裹 sql.Open 和健康检查，确保数据库连接延迟加载且线程安全；waitForDBReady 需区分可重试（如超时、连接拒绝）与不可重试错误（如认证失败、库不存在），并实现指数退避。
延迟加载数据库连接必须用 sync.Once
直接在全局变量里调用 sql.Open 就不是延迟加载；而裸写 if db == nil { db = sql.Open(...) } 在并发下会 panic —— 多个 goroutine 同时进入判断，都执行 sql.Open，后续可能复用已关闭或未初始化完成的 *sql.DB。
正确做法是用 sync.Once 包裹初始化逻辑，确保只执行一次且线程安全：
var (
db *sql.DB
once sync.Once
err error
)
<p>func GetDB() (*sql.DB, error) {
once.Do(func() {
db, err = sql.Open("mysql", dsn)
if err != nil {
return
}
// 立即做启动期健康检查（见下一节）
err = waitForDBReady(context.Background(), db)
})
return db, err
}-
sync.Once是标准库唯一推荐的懒加载原语，比手写sync.RWMutex+ 双检锁更可靠 - 不要在
once.Do里做耗时操作（比如读大配置、拉远程密钥），否则首次调用会被卡住 - 如果初始化失败，
err会被缓存，后续调用GetDB()仍返回同一错误，不会重试
waitForDBReady 必须区分可恢复与不可恢复错误
服务启动时 sql.Open 成功不代表 MySQL 已就绪。Docker Compose 启动顺序错乱、K8s InitContainer 延迟、MySQL 自身初始化耗时，都会导致首次 db.PingContext() 失败。但不是所有错误都该重试。
只对以下错误类型做指数退避重试：
立即学习“go语言免费学习笔记（深入）”；
-
context.DeadlineExceeded（注意：这是上一次请求超时，新请求需重置 context） -
net.OpError，如dial tcp: i/o timeout、connection refused - gRPC 中的
codes.Unavailable
遇到以下错误应立刻退出，不重试：
-
ERROR 1045 (28000): Access denied（认证失败） -
ERROR 1049 (42000): Unknown database（库不存在） - 任何包含
parse、syntax、invalid的 DSN 解析错误
示例关键逻辑：
func waitForDBReady(ctx context.Context, db *sql.DB) error {
backoff := time.Second
for {
if err := db.PingContext(ctx); err == nil {
return nil
} else if !isRetryableError(err) {
return err
}
select {
case <-time.After(backoff):
backoff *= 2
if backoff > 8*time.Second {
backoff = 8 * time.Second
}
case <-ctx.Done():
return ctx.Err()
}
}
}延迟加载后必须配好连接池参数，不能依赖手动 Ping
很多人以为“懒加载 + 定时 db.PingContext()”能保连接活跃，其实这是反模式。原因有三：
-
db.PingContext()只探测池中一个空闲连接，其他连接可能早已被 MySQL 主动断开（比如wait_timeout=28800） - 频繁 ping 制造无效负载，且无法解决连接泄漏问题
- 运行时连接失效靠的是连接池生命周期管理，不是探测
真正起作用的是这三行（必须在 sql.Open 后立即设置）：
db.SetMaxOpenConns(25) db.SetMaxIdleConns(10) db.SetConnMaxLifetime(4 * time.Minute)
-
SetConnMaxLifetime必须比 MySQL 的wait_timeout短（建议短 1–2 分钟），否则复用陈旧连接必报invalid connection -
SetMaxOpenConns不要设为 0（不限制），高并发下容易打爆数据库 -
SetMaxIdleConns应 ≤SetMaxOpenConns，否则空闲连接堆积反而拖慢回收
DSN 中的 timeout 参数有效，但 retry=true 是无效字段
Go MySQL 驱动（github.com/go-sql-driver/mysql）只识别部分 DSN 参数，很多网上教程写的字段根本不起作用。
真正生效的超时类参数包括：
-
timeout：连接建立总超时（对应net.DialTimeout） -
readTimeout：读操作超时 -
writeTimeout：写操作超时
以下字段是常见误区，驱动完全忽略：
failover=trueretry=truemaxRetries=3
重试逻辑必须由 Go 代码自己控制，不能寄希望于 DSN。例如这个 DSN 是错的：
"user:pass@tcp(127.0.0.1:3306)/db?timeout=5s&retry=true"
其中 retry=true 被静默丢弃，实际不会重试。
延迟加载最易被忽略的点：它只解决“第一次初始化时机”，不解决“连接是否可用”。可用性靠 waitForDBReady + 连接池参数组合保障，缺一不可。
