Go 中使用 database/sql 包时应全局复用单一 sql.DB 实例_技术教程

在 go 应用中，`database/sql.open` 应仅调用一次，创建一个全局共享的 `*sql.db` 实例；它本身是并发安全的，并内置连接池，无需也不应为每个函数单独 open 或 close。

Go 的 database/sql 包设计核心之一，就是将连接管理与业务逻辑解耦。sql.Open 并不立即建立数据库连接，而只是初始化一个*数据库句柄（`sql.DB）**，该句柄内部维护一个可配置的连接池（idle & in-use connections），并天然支持高并发——多个 goroutine 可安全、高效地复用同一个*sql.DB` 实例。

✅ 正确做法（推荐且标准）：

在应用启动时（如 main() 或 init() 阶段）调用一次 sql.Open；
紧接着调用 db.Ping() 进行连接验证（确保 DSN 有效、网络可达、认证通过）；
将该 *sql.DB 实例作为依赖注入到需要访问数据库的组件（如 service 层、handler 函数），或通过包级变量/依赖容器全局可用；
全程不调用 db.Close()（除非程序即将退出，且需优雅释放资源）。

// 示例：正确初始化 DB 实例
var db *sql.DB

func initDB() error {
    var err error
    db, err = sql.Open("postgres", "user=app dbname=test sslmode=disable")
    if err != nil {
        return fmt.Errorf("failed to open database: %w", err)
    }

    // 设置连接池参数（可选但推荐）
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(25)
    db.SetConnMaxLifetime(5 * time.Minute)

    // 验证连接有效性
    if err = db.Ping(); err != nil {
        return fmt.Errorf("failed to ping database: %w", err)
    }
    return nil
}

❌ 错误做法辨析：

为每个函数调用 sql.Open（选项 1）：
每次都新建 *sql.DB，不仅重复解析 DSN、初始化连接池，还会导致大量闲置连接句柄堆积，消耗系统资源（文件描述符、内存），且无法复用连接池，严重损害性能与稳定性。
“共用同一个连接”（选项 2 的误解）：
*sql.DB 不代表单个 TCP 连接，而是一个连接池管理器。你调用 db.Query 或 db.Exec 时，底层自动从池中获取空闲连接（或新建）、执行语句、归还连接——开发者完全无需关心“哪个连接被用了”。因此，“让 100 个函数共用一个连接”是概念错误；真正共用的是同一个连接池。

? 关键注意事项：