本文详解 go 项目中如何安全、可靠地声明和共享 *sql.db 全局变量，重点解决因变量作用域误用导致的 nil 指针 panic，并提供更推荐的无全局变量依赖的结构化方案。
本文详解 go 项目中如何安全、可靠地声明和共享 *sql.db 全局变量，重点解决因变量作用域误用导致的 nil 指针 panic，并提供更推荐的无全局变量依赖的结构化方案。
在 Go 多文件项目中，将数据库连接（如 *sql.DB）声明为包级全局变量看似简洁，却极易因变量遮蔽（variable shadowing） 导致运行时 panic。典型错误如题所示：a.go 中使用 db, err := sql.Open(…) 初始化全局 db，但因 := 同时声明并初始化了 db 和 err，实际创建的是局部变量 db，覆盖了同名全局变量，导致 b.go 中引用的 db 仍为 nil，调用 db.Query() 时触发 invalid memory address or nil pointer dereference。
✅ 正确方式一：修复全局变量初始化（显式赋值）
关键在于避免使用 := 对已声明的全局变量重新声明。需先声明 err，再用 = 赋值：
// a.go package main import ( "database/sql" "github.com/gin-gonic/gin" _ "github.com/go-sql-driver/mysql" ) var db *sql.DB // 全局声明（零值为 nil） func main() { var err error // 显式声明 err 变量（不使用 :=） // 使用 = 赋值，确保写入全局 db db, err = sql.Open("mysql", "root:password@unix(/var/run/mysqld/mysqld.sock)/test.com?collation=utf8_general_ci") if err != nil { panic("failed to open database: " + err.Error()) } // 必须调用 Ping() 验证连接有效性（sql.Open 不立即建立连接） if err = db.Ping(); err != nil { panic("failed to ping database: " + err.Error()) } // 注意：此处不应 defer db.Close() // 因 db 是长期存活的全局资源，应在程序退出前关闭（如使用 os.Interrupt 信号监听） r := gin.New() r.GET("/api/v1/users", func(c *gin.Context) { users := GetUsers() c.JSON(200, users) }) r.Run(":3000") }// b.go package main import "log" type User struct { Id int `json:"id"` Name string `json:"name"` } func GetUsers() []User { rows, err := db.Query("SELECT id, name FROM users") // db 已被正确初始化 if err != nil { log.Printf("query failed: %v", err) return nil } defer rows.Close() var users []User for rows.Next() { var u User if err := rows.Scan(&u.Id, &u.Name); err != nil { log.Printf("scan failed: %v", err) continue } users = append(users, u) } return users }⚠️ 重要注意事项：
- sql.Open() 仅验证 DSN 格式，不建立真实连接；必须调用 db.Ping() 才能确认连接池可用。
- defer db.Close() 不可放在 main() 中——它会在 main 函数返回时立即关闭连接，导致后续请求失败。应通过 os.signal 在进程退出前优雅关闭。
- 全局变量虽可行，但会增加测试难度（无法为不同测试用例注入独立 DB 实例），且违反依赖显式化原则。
✅ 推荐方式二：消除全局状态，依赖注入（更佳实践）
更符合 Go 工程规范的做法是*避免全局变量，改用结构体封装依赖，并通过方法接收者或函数参数传递 `sql.DB`**：
// a.go package main import ( "database/sql" "os" "os/signal" "syscall" "github.com/gin-gonic/gin" _ "github.com/go-sql-driver/mysql" ) type App struct { db *sql.DB } func NewApp(dsn string) (*App, error) { db, err := sql.Open("mysql", dsn) if err != nil { return nil, err } if err = db.Ping(); err != nil { return nil, err } return &App{db: db}, nil } func (a *App) Run(port string) { r := gin.New() r.Use(gin.Logger()) r.GET("/api/v1/users", a.handleGetUsers) // 启动服务并监听退出信号 go func() { if err := r.Run(port); err != nil && err != http.ErrServerClosed { log.Fatalf("server failed: %v", err) } }() quit := make(chan os.Signal, 1) signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) <-quit // 优雅关闭数据库 if err := a.db.Close(); err != nil { log.Printf("failed to close db: %v", err) } log.Println("server stopped") } func (a *App) handleGetUsers(c *gin.Context) { users := GetUsers(a.db) // 显式传入 db c.JSON(200, users) } func main() { app, err := NewApp("root:password@unix(/var/run/mysqld/mysqld.sock)/test.com?collation=utf8_general_ci") if err != nil { panic(err) } app.Run(":3000") }// b.go package main import "log" type User struct { Id int `json:"id"` Name string `json:"name"` } // 接收 *sql.DB 作为参数，完全解耦于全局状态 func GetUsers(db *sql.DB) []User { rows, err := db.Query("SELECT id, name FROM users") if err != nil { log.Printf("query failed: %v", err) return nil } defer rows.Close() var users []User for rows.Next() { var u User if err := rows.Scan(&u.Id, &u.Name); err != nil { log.Printf("scan failed: %v", err) continue } users = append(users, u) } return users }✅ 总结
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 修复全局变量 | 改动小，快速修复现有代码 | 难以测试、隐式依赖、生命周期管理易出错 | 小型脚本或临时项目 |
| 依赖注入（结构体封装） | 可测试性强、依赖显式、易于扩展（如添加 redis、Logger）、符合 Go 最佳实践 | 初始代码稍多 | 所有生产级 Web 服务 |
强烈建议采用依赖注入方式：它让数据访问层真正“可移植”，便于单元测试（可传入 sqlmock）、支持多环境配置，并为未来引入连接池配置、中间件、监控埋点等打下坚实基础。全局变量不是 Go 的设计哲学——清晰、可控、可组合的依赖关系，才是构建健壮服务的关键。