本文详解 Go 多文件项目中因短变量声明（:=）导致全局 *sql.DB 为 nil 的典型错误，提供两种专业级修复方案：修正作用域赋值与推荐的依赖注入式设计。
本文详解 go 多文件项目中因短变量声明（`:=`）导致全局 `*sql.db` 为 nil 的典型错误，提供两种专业级修复方案：修正作用域赋值与推荐的依赖注入式设计。
在 Go 项目中跨文件共享数据库连接（如 *sql.DB）是常见需求，但若处理不当，极易引发运行时 panic —— 典型表现为 nil pointer dereference。从错误堆栈可见，b.go 中调用 db.Query(...) 时 db 为 nil，根本原因在于 a.go 中对全局变量 db 的初始化被错误地“遮蔽”了。
? 根本原因：短变量声明 := 创建了局部变量
在 a.go 的 main() 函数中：
db, err := sql.Open(...) // ❌ 错误！此处的 db 是新声明的局部变量
该行使用 := 同时声明并初始化两个变量。由于 db 已在包级作用域声明为 var db *sql.DB，Go 规则要求：仅当所有左侧变量均为新声明时，:= 才合法。但此处 db 并非新变量，因此 Go 实际将 db 解释为一个全新的局部变量，与包级 db 完全无关。结果是：
- 包级 db 始终为 nil
- 局部 db 在 main() 返回后即被销毁
- b.go 中访问的仍是未初始化的包级 db → panic
✅ 方案一：修正赋值方式（快速修复）
只需将 := 改为 =，并提前声明 err（确保左侧所有变量均已声明）：
// a.go
func main() {
var err error // 显式声明 err 变量
db, err = sql.Open("mysql", "root:password@unix(/var/run/mysqld/mysqld.sock)/test.com?collation=utf8_general_ci")
if err != nil {
panic("DB connection failed: " + err.Error())
}
// ⚠️ 关键：移除 defer db.Close()！它会在 main() 结束时关闭连接
// 正确做法：在程序退出前关闭（见下方注意事项）
if err = db.Ping(); err != nil {
panic("DB ping failed: " + err.Error())
}
// ... Gin 路由设置
}同时，b.go 中需确保 db 非 nil（生产环境应添加检查）：
// b.go
func GetUsers() []User {
users := []User{}
// 生产建议：增加 nil 检查
if db == nil {
log.Fatal("database connection is not initialized")
}
rows, err := db.Query("SELECT id, name FROM users")
if err != nil {
log.Fatal("query failed: ", err)
}
defer rows.Close()
for rows.Next() {
var u User
if err := rows.Scan(&u.Id, &u.Name); err != nil {
log.Fatal("scan failed: ", err)
}
users = append(users, u)
}
return users
}⚠️ 重要注意事项：
- defer db.Close() 必须移除！否则 main() 函数退出时连接即被关闭，后续请求全部失败。
- 应在程序优雅退出时关闭 DB（例如监听 os.Interrupt 信号后调用 db.Close()）。
- sql.Open() 不会立即建立连接，db.Ping() 才真正验证连接可用性。
✅ 方案二（推荐）：依赖注入 —— 消除全局状态
更符合 Go 工程实践的方式是避免全局变量，通过结构体封装依赖，并以方法接收者形式传递：
// a.go
package main
import (
"database/sql"
"log"
"os"
"os/signal"
"syscall"
"github.com/gin-gonic/gin"
_ "github.com/go-sql-driver/mysql"
)
type App struct {
db *sql.DB
}
func (app *App) GetUsers() []User {
users := []User{}
rows, err := app.db.Query("SELECT id, name FROM users")
if err != nil {
log.Fatal("query failed: ", err)
}
defer rows.Close()
for rows.Next() {
var u User
if err := rows.Scan(&u.Id, &u.Name); err != nil {
log.Fatal("scan failed: ", err)
}
users = append(users, u)
}
return users
}
func (app *App) Run() {
r := gin.New()
r.Use(gin.Logger())
r.GET("/api/v1/users", func(c *gin.Context) {
users := app.GetUsers()
c.JSON(200, users)
})
// 启动服务并监听退出信号
go func() {
if err := r.Run(":3000"); 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 := app.db.Close(); err != nil {
log.Printf("failed to close database: %v", err)
}
log.Println("server stopped")
}
func main() {
db, err := sql.Open("mysql", "root:password@unix(/var/run/mysqld/mysqld.sock)/test.com?collation=utf8_general_ci")
if err != nil {
log.Fatal("DB open failed: ", err)
}
if err = db.Ping(); err != nil {
log.Fatal("DB ping failed: ", err)
}
app := &App{db: db}
app.Run()
}// b.go（仅定义数据结构，无需 import database/sql）
package main
type User struct {
Id int `json:"id"`
Name string `json:"name"`
}✅ 总结与最佳实践
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 修正 = 赋值 | 修改少、见效快 | 仍依赖全局变量，测试困难，易引发竞态 | 小型脚本或临时修复 |
| 依赖注入（结构体封装） | 可测试性强、解耦清晰、生命周期可控、符合 Go idioms | 初期代码略多 | 所有生产级 Web 服务 |
终极建议：
- 永远避免在 main() 中使用 defer db.Close()；
- 使用 sql.Open() 后务必调用 db.Ping() 验证连接；
- 将数据库连接作为依赖项显式传递，而非隐式全局状态；
- 在应用退出前统一关闭资源，确保优雅终止。
通过以上任一方案，即可彻底解决跨文件 *sql.DB 为 nil 的问题，构建健壮、可维护的 Go 数据库应用。
