Go 中 database/sql 连接池最佳实践

Go 的 database/sql 包原生支持连接池，推荐全局复用单个 *sql.DB 实例（非连接本身），无需手动实现单例锁；其生命周期应与应用一致，通常无需显式关闭，但可在程序退出前调用 db.Close() 确保资源释放。

Go 的 `database/sql` 包原生支持连接池，推荐全局复用单个 `*sql.DB` 实例（非连接本身），无需手动实现单例锁；其生命周期应与应用一致，通常无需显式关闭，但可在程序退出前调用 `db.Close()` 确保资源释放。

在 Go 中管理数据库连接，核心误区是将 *sql.DB 误解为“单个数据库连接”——实际上，它是一个连接池管理器（database handle），线程安全、内置连接复用与自动重连逻辑，并默认启用连接池（可配置 SetMaxOpenConns、SetMaxIdleConns 等）。因此，最佳实践是：*在整个应用生命周期内只创建一次 `sql.DB` 实例，并全局共享**。

✅ 推荐初始化方式（简洁、安全、可测试）

避免在 init() 函数中隐式初始化（不利于单元测试和配置注入），推荐显式初始化函数，在 main() 中集中调用：

package main

import (
    "database/sql"
    "fmt"
    "log"
    "time"

    _ "github.com/lib/pq" // PostgreSQL 驱动（按需替换）
)

var db *sql.DB

// DBConfig 封装数据库配置，便于测试与环境隔离
type DBConfig struct {
    Host     string
    Port     int
    User     string
    Password string
    Name     string
}

// InitDB 初始化并验证数据库连接池
func InitDB(cfg DBConfig) error {
    connStr := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
        cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.Name)

    d, err := sql.Open("postgres", connStr)
    if err != nil {
        return fmt.Errorf("failed to open database: %w", err)
    }

    // 设置连接池参数（生产环境建议显式配置）
    d.SetMaxOpenConns(25)
    d.SetMaxIdleConns(25)
    d.SetConnMaxLifetime(5 * time.Minute)
    d.SetConnMaxIdleTime(5 * time.Minute)

    // Ping 以验证底层连接可达性（阻塞直到成功或超时）
    if err := d.Ping(); err != nil {
        d.Close() // 失败时主动清理
        return fmt.Errorf("failed to ping database: %w", err)
    }

    db = d
    log.Println("✅ Database connection pool initialized successfully")
    return nil
}

// GetDB 提供安全访问（可选：用于依赖注入场景）
func GetDB() *sql.DB {
    return db
}

在 main() 中初始化并优雅关闭：

func main() {
    cfg := DBConfig{
        Host:     "localhost",
        Port:     5432,
        User:     "app",
        Password: "secret",
        Name:     "myapp",
    }

    if err := InitDB(cfg); err != nil {
        log.Fatal("❌ Failed to initialize DB:", err)
    }
    defer db.Close() // 推荐：确保程序退出前释放所有连接和 goroutines

    // 启动 HTTP server 或其他业务逻辑...
}

⚠️ 关键注意事项

• 不要频繁 sql.Open：每次调用都新建连接池管理器，导致资源泄漏和连接耗尽。
• db.Close() 并非必须，但强烈推荐：虽然文档称 “rarely necessary”，但显式调用可立即终止所有后台健康检查 goroutine、释放内存，并避免进程退出时连接未及时回收（尤其在容器化环境中）。
• Ping() 不可省略：sql.Open 仅校验 DSN 格式，不建立实际连接；Ping() 才真正触发首次连接并验证服务可达性。
• 避免全局变量滥用：若需更高可测试性或模块解耦，可将 *sql.DB 作为依赖项注入到 Repository/Service 层（如通过结构体字段或函数参数传递），而非强依赖包级变量。

? 总结

Go 的数据库连接管理哲学是「创建一次，共享终身，延迟关闭」。*sql.DB 是轻量、并发安全的句柄，其内部连接池已高度优化。你只需专注配置合理参数、验证连接、统一生命周期管理——无需 Spring 式 IoC 容器，也无需手写单例锁。真正的工程重点，应转向 SQL 注入防护、上下文超时控制（db.QueryContext）、错误分类处理及可观测性集成（如连接池指标暴露）。