本文详解如何在Go项目中安全、高效地全局复用*sql.DB连接池，涵盖导出规则、初始化时机、连接池配置及跨包调用规范，避免连接泄露、并发不安全和“unknown driver”等常见错误。
本文详解如何在go项目中安全、高效地全局复用*sql.db连接池，涵盖导出规则、初始化时机、连接池配置及跨包调用规范，避免连接泄露、并发不安全和“unknown driver”等常见错误。
在Go语言Web开发中，将*sql.DB作为全局连接池对象在多个HTTP handler、model或service间共享，是提升性能与资源利用率的标准做法。但实现不当极易引发连接耗尽、空指针 panic、驱动未注册或并发竞争等问题。以下为经过生产验证的完整实践方案。
✅ 正确导出与初始化：首字母大写 + 显式初始化函数
Go语言中，只有首字母大写的标识符（如 Db, Err）才可被其他包访问。原代码中 var db *sql.DB 是小写，属于包级私有变量，common.db 在外部包中不可见——这正是你调用失败的根本原因。
应改为：
// common/mysql.go
package common
import (
"database/sql"
"fmt"
"time"
_ "github.com/go-sql-driver/mysql" // 空白导入：触发驱动注册
)
var Db *sql.DB // ✅ 首字母大写，可导出
var Err error // ✅ 同理
// InitDB 初始化数据库连接池（推荐命名，语义清晰）
func InitDB() error {
dsn := "root:@tcp(localhost:3306)/mysqlapi?parseTime=true&loc=Local"
Db, Err = sql.Open("mysql", dsn)
if Err != nil {
return fmt.Errorf("failed to parse DSN: %w", Err)
}
// ⚠️ 关键：连接池参数必须在首次查询前设置！
Db.SetMaxOpenConns(25) // 最大打开连接数（建议 ≤ MySQL max_connections × 0.8）
Db.SetMaxIdleConns(6) // 最大空闲连接数（建议为 MaxOpenConns 的 1/4～1/2）
Db.SetConnMaxLifetime(60 * time.Minute) // 连接最大存活时间（防老化）
Db.SetConnMaxIdleTime(30 * time.Minute) // 空闲连接最大保留时间（Go 1.15+）
// ✅ Ping 验证连通性（触发真实建连）
if Err = Db.Ping(); Err != nil {
return fmt.Errorf("failed to connect to database: %w", Err)
}
// ✅ 表迁移（建议移至独立 migrate 包，此处仅示意）
if Err = migratePersonTable(); Err != nil {
return fmt.Errorf("migration failed: %w", Err)
}
return nil
}
func migratePersonTable() error {
stmt := `CREATE TABLE IF NOT EXISTS person (
id INT NOT NULL AUTO_INCREMENT,
first_name VARCHAR(40),
last_name VARCHAR(40),
PRIMARY KEY (id)
) ENGINE=InnoDB`
_, err := Db.Exec(stmt)
return err
}? 关键点说明：
立即学习“go语言免费学习笔记（深入）”；
sql.Open不立即建连，仅校验DSN并初始化连接池结构；Db.Ping()才真正发起TCP握手。- 所有
SetXXX方法（如SetMaxOpenConns）必须在Ping()或首次Query前调用，否则默认值（如MaxOpenConns=0即无上限）可能引发MySQL连接数爆满。- DSN中必须包含
parseTime=true（否则time.Time字段扫描失败）和loc=Local（避免时区错乱）。
✅ 跨包安全使用：统一初始化入口 + 全局单例
在 main.go 或应用启动入口处一次性调用 common.InitDB()，确保 common.Db 已就绪后再启动HTTP服务：
// main.go
package main
import (
"log"
"net/http"
"your-project/common" // 替换为你的实际路径
"your-project/handlers"
)
func main() {
// ✅ 1. 初始化数据库（必须最先执行）
if err := common.InitDB(); err != nil {
log.Fatal("Database init failed:", err)
}
defer common.Db.Close() // 应用退出时关闭连接池
// ✅ 2. 注册路由（此时 common.Db 已可用）
http.HandleFunc("/users", handlers.ListUsers)
http.HandleFunc("/users/", handlers.GetUser)
log.Println("Server starting on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}在 models 包中直接使用 common.Db（无需再次 import "common" 中的 db 变量）：
// models/user.go
package models
import (
"database/sql"
"fmt"
"your-project/common" // ✅ 导入 common 包
)
type User struct {
Id int
First_Name string
Last_Name string
}
func SelectAll() ([]*User, error) {
rows, err := common.Db.Query("SELECT id, first_name, last_name FROM person")
if err != nil {
return nil, fmt.Errorf("query failed: %w", err)
}
defer rows.Close() // ✅ 必须关闭 rows，否则连接永不归还池
var users []*User
for rows.Next() {
var u User
if err := rows.Scan(&u.Id, &u.First_Name, &u.Last_Name); err != nil {
return nil, fmt.Errorf("scan failed: %w", err)
}
users = append(users, &u)
}
// ✅ 检查 rows 遍历是否因错误中断
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("rows iteration error: %w", err)
}
return users, nil
}⚠️ 重要注意事项与避坑指南
-
❌ 禁止在 handler 内
sql.Open：每次请求都新建*sql.DB会快速耗尽文件描述符（too many open files），且无法复用连接。 - *✅ `sql.DB` 是线程安全的**：可全局复用，无需加锁或 per-request 创建。
-
⚠️
defer db.Close()位置错误：原mysql.go中defer db.Close()在connectDB()函数内执行，会导致连接池立即关闭——必须放在main()的defer中，或由应用生命周期管理。 -
? 敏感信息外置：密码、地址等绝不可硬编码，应通过环境变量（
os.Getenv("DB_DSN")）或配置文件加载。 -
?️ SQL注入防护：永远使用参数化查询（
WHERE id = ?），禁止字符串拼接SQL。 -
? 错误处理要完整：
rows.Scan()和rows.Err()都需检查，遗漏后者将掩盖遍历中途的IO错误。
遵循以上规范，你的Go应用即可安全、高效、可维护地实现MySQL连接池全局共享，支撑高并发业务场景。
