sync.Once 是 Go 中实现线程安全延迟初始化的最安全轻量方式，它确保 sql.Open 及连接池配置（如 SetMaxOpenConns、Ping 验证）仅执行一次，避免 init() 或全局变量初始化导致的配置未就绪、启动 panic、参数丢失和资源泄漏。
直接结论：用 sync.Once 包裹 sql.Open 及其后续配置，是最安全、最轻量的延迟加载方式；不要在 init() 或全局变量赋值时直接初始化连接池。
为什么不能在包初始化时建连接池
Go 的 init() 函数和全局变量初始化发生在程序启动阶段，此时配置可能还没加载（比如从环境变量、远程配置中心读取），或数据库服务尚未就绪。硬编码连接字符串或提前调用 sql.Open 容易导致启动失败、panic 或静默连接超时。
常见错误现象：
-
panic: failed to connect to `host=localhost user=postgres database=...`: dial error—— 启动即崩，但真实问题是 DB 尚未 ready - 连接池参数（如
SetMaxOpenConns）被忽略，因为sql.Open返回的*sql.DB被丢弃或未及时配置 - 多个包各自初始化自己的
*sql.DB，造成资源冗余和连接泄漏
用 sync.Once 实现线程安全的首次访问加载
sync.Once 保证初始化函数只执行一次，且并发调用时自动阻塞等待，无需额外锁或判断逻辑。它天然适配“首次访问才建池”的语义。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 声明一个包级
*sql.DB变量和对应的sync.Once实例 - 封装一个导出函数（如
GetDB()），内部调用once.Do()执行初始化 - 在
once.Do回调里完成sql.Open、错误处理、连接池参数设置（SetMaxOpenConns、SetConnMaxLifetime等） - 不要在回调外做任何依赖
*sql.DB的操作（比如预热查询），否则可能触发竞态
示例代码片段：
var (
dbPool *sql.DB
dbOnce sync.Once
)
<p>func GetDB() <em>sql.DB {
dbOnce.Do(func() {
var err error
dbPool, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatal("failed to open db:", err)
}
dbPool.SetMaxOpenConns(25)
dbPool.SetMaxIdleConns(10)
dbPool.SetConnMaxLifetime(5 </em> time.Minute)
// 必须验证连接是否可用，避免返回一个“假池”
if err = dbPool.Ping(); err != nil {
log.Fatal("failed to ping db:", err)
}
})
return dbPool
}容易踩的坑：延迟加载 ≠ 延迟验证
只靠 sql.Open 不代表连接池就可用——它只是返回一个“懒连接器”，真正建连发生在第一次 Ping() 或 Query() 时。如果跳过 Ping()，首次业务请求仍可能因网络/认证失败而卡住或 panic。
其他关键点：
-
sql.Open本身不建立物理连接，所以它的失败通常来自 DSN 格式错误，而非网络问题 -
dbPool.Ping()是必须的，它强制建立并验证一条连接，把错误前置到初始化阶段 - 不要在
once.Do外部调用dbPool.Ping()，否则并发下可能多次执行 - 若配置动态变更（如重载 DB URL），
sync.Once不支持重置，需换用更复杂的机制（如带版本号的 lazy loader）
真正难的不是“怎么写”，而是想清楚：这个连接池谁负责销毁？是否要支持热重载？有没有跨 package 共享需求？这些问题一旦模糊，sync.Once 就会变成隐藏的耦合点。
