GORM 本身不内置单例，但必须用单例模式管理 gorm.DB 实例，否则会耗尽 MySQL 连接数或引发竞态；应使用 sync.Once 全局初始化并统一配置底层 sql.DB 连接池。
直接结论：GORM 本身不内置单例，但必须用单例模式管理 gorm.DB 实例，否则会快速耗尽 MySQL 连接数或引发竞态。
为什么不能每次请求都调用 gorm.Open
每次调用 gorm.Open 都会新建一个 gorm.DB 实例，而每个实例背后默认维护独立的连接池（*sql.DB）。Go 的 database/sql 连接池是线程安全的，但多个池之间无法共享连接、无法复用空闲连接，还会导致：
- MySQL 服务端连接数暴涨（尤其在高并发下），触发
Too many connections错误 - 重复初始化配置（如日志、回调、插件），浪费资源
- 全局钩子（如
BeforeCreate）需注册多次才生效，逻辑错乱 - 无法统一控制连接池参数（
SetMaxOpenConns等）
sync.Once 是最轻量可靠的初始化方式
Go 标准库的 sync.Once 保证函数只执行一次，天然适配单例初始化场景。它比手动加锁更简洁、比全局变量 + if 判断更安全。
典型写法如下（注意：必须导出为包级变量，供其他文件调用）：
var (
db *gorm.DB
once sync.Once
)
func GetDB() (*gorm.DB, error) {
once.Do(func() {
dsn := "user:pass@tcp(127.0.0.1:3306)/test?charset=utf8mb4&parseTime=True&loc=Local"
var err error
db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{
Logger: logger.Default.LogMode(logger.Info),
})
if err != nil {
panic(err) // 或返回 err，由上层处理
}
// 统一设置底层 *sql.DB 连接池
sqlDB, _ := db.DB()
sqlDB.SetMaxOpenConns(100)
sqlDB.SetMaxIdleConns(20)
sqlDB.SetConnMaxLifetime(time.Hour)
})
return db, nil
}
关键点：
-
once.Do内部不能有阻塞或长时操作，否则首次调用会卡住所有 goroutine - 不要在
init()函数里调用gorm.Open—— DSN 可能依赖配置加载，顺序难控 -
GetDB()返回的是同一个*gorm.DB实例，可安全并发使用
别把 gorm.DB 当成“连接”，它是带连接池的句柄
新手常误以为 db.Create(...) 会新建数据库连接。其实 gorm.DB 是一个轻量句柄，真正建连、复用、回收都由其内部封装的 *sql.DB 完成。你只需确保：
- 全局只创建一个
*gorm.DB实例（靠sync.Once） - 对该实例调用
.DB().SetMaxOpenConns()等方法统一调优 - 避免在 handler 里用
db.Session(...)无节制派生新gorm.DB—— 每个 session 都是新句柄，但共享底层连接池；过度使用会增加 GC 压力，且可能掩盖连接泄漏
如果真需要隔离（如读写分离、事务上下文），应基于已有 *gorm.DB 创建 session，而不是反复 Open。
常见坑：配置未生效、panic 不被捕获、测试环境污染
这些问题往往不是 GORM 的锅，而是单例初始化时机或方式不对：
- DNS 解析失败或 MySQL 未就绪时 panic，导致整个服务起不来 → 改用返回 error 而非 panic，让启动逻辑可重试
- 单元测试中多次调用
GetDB()，但sync.Once已触发，旧连接仍连着测试库 → 测试前显式关闭：sqlDB.Close()，或改用内存 SQLite 隔离 - 日志级别没生效（如
LogMode(logger.Info)不打印 SQL）→ 确保gorm.Config是传给gorm.Open的第二个参数，不是后续调用 - 忘记调用
sqlDB.SetConnMaxLifetime→ 连接长期空闲后被 MySQL 主动断开，下次复用时报invalid connection
真正复杂的地方在于：单例只是起点，后续所有模型定义、钩子注册、事务嵌套，都依赖这个唯一句柄的状态一致性。一旦初始化漏了某项配置，排查起来往往要翻遍整个启动链路。
