Go中正确初始化MySQL连接避免nil指针错误

许多开发者在用 Go 连接 MySQL 时，都会遇到一个经典“陷阱”：代码看上去没有问题，但一运行就 panic，报错为 nil pointer dereference。本文将深入拆解这一常见失误，并提供一个既安全又易于维护的数据库初始化方案，附上完整可运行示例。

首先来看最常见的陷阱：变量声明与赋值混淆。不少新手（甚至一些有经验的开发者）在编写 connectDb() 函数时，习惯使用 db, err := sql.Open(...)，结果导致 db 成为函数内部的局部变量，而不是给包级全局变量 var db *sql.DB 赋值。于是全局 db 始终是 nil，后续调用 db.Exec(...) 自然触发 invalid memory address or nil pointer dereference。注意，问题并不出在连接字符串（例如 "root:abc@/abc" 在本地 MySQL 默认配置下其实可用），而是变量作用域惹的祸。

✅ 正确实践：显式赋值与连接验证

另一个容易被忽略的关键点：sql.Open() 仅验证 DSN 格式并返回一个 *sql.DB 句柄，它并未真正建立数据库连接。要确认连接是否可用，必须调用 db.Ping()。因此，不要指望 Open 一下就能直接使用。此外，虽然本例保留全局变量以兼容原有结构，但从长远维护角度，更推荐将数据库实例作为返回值传递，或采用依赖注入（如 Google 的 Wire 框架）来管理。

下面是修复后的关键代码，已整合进完整结构：

package main

import (
    "database/sql"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
    _ "github.com/go-sql-driver/mysql" // MySQL 驱动（注意：仅需导入，无需赋值）
)

var INDEX_HTML []byte

// 全局 db 变量（修复后：由 initDB 初始化）
var db *sql.DB

func main() {
    fmt.Println("Starting server on port 8080")
    http.HandleFunc("/", IndexHandler)
    http.HandleFunc("/addlist", AddListHandler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func AddListHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != "POST" {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }
    if err := r.ParseForm(); err != nil {
        http.Error(w, "Failed to parse form", http.StatusBadRequest)
        return
    }
    item := r.FormValue("item") // 更安全地获取表单值
    if item == "" {
        http.Error(w, "Item cannot be empty", http.StatusBadRequest)
        return
    }
    // ✅ 确保 db 已初始化且非 nil
    if db == nil {
        http.Error(w, "Database not initialized", http.StatusInternalServerError)
        return
    }
    // 执行插入（使用 ? 占位符防 SQL 注入）
    _, err := db.Exec("INSERT INTO ListItems(items) VALUES (?)", item)
    if err != nil {
        log.Printf("DB insert error: %v", err)
        http.Error(w, "Failed to sa ve item", http.StatusInternalServerError)
        return
    }
    http.Redirect(w, r, "/", http.StatusTemporaryRedirect)
}

func IndexHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    w.Write(INDEX_HTML)
}

func init() {
    var err error
    INDEX_HTML, err = ioutil.ReadFile("./templates/index.html")
    if err != nil {
        log.Fatalf("Failed to read index.html: %v", err)
    }
    db, err = initDB() // ✅ 使用 = 赋值，而非 :=
    if err != nil {
        log.Fatalf("Failed to initialize database: %v", err)
    }
}

// ✅ 推荐：将 DB 初始化逻辑封装为函数，显式返回 *sql.DB 和 error
func initDB() (*sql.DB, error) {
    // 构建 DSN（推荐显式指定 tcp 和端口，增强可读性与可移植性）
    dsn := "root:abc@tcp(127.0.0.1:3306)/abc?charset=utf8mb4&parseTime=True&loc=Local"
    db, err := sql.Open("mysql", dsn)
    if err != nil {
        return nil, fmt.Errorf("sql.Open failed: %w", err)
    }
    // ✅ 关键：Ping 以验证实际连接
    if err := db.Ping(); err != nil {
        db.Close() // 立即关闭无效连接
        return nil, fmt.Errorf("db.Ping failed: %w", err)
    }
    // ✅ （可选但推荐）设置连接池参数
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(25)
    db.SetConnMaxLifetime(5 * 60 * time.Second) // 5分钟
    log.Println("✅ Database connection established successfully")
    return db, nil
}

// 注意：记得在程序退出前关闭数据库（例如在 main 函数末尾或使用 defer）
// defer db.Close()

⚠️ 重要注意事项

• sql.Open() ≠ 连接建立：它仅初始化连接池，db.Ping() 才执行真正的网络握手。
• 避免全局变量滥用：尽管本例保留全局 db 以兼容原有结构，但在大型项目中应优先通过构造函数传递 *sql.DB 实例，或采用依赖注入框架（如 Wire）。
• DSN 安全建议：
  • 密码等敏感数据严禁硬编码，建议通过环境变量（os.Getenv("DB_PASSWORD")）或配置文件读取。
  • 生产环境应启用 TLS（如 tls=true）并禁止 root 远程登录。
• 错误处理不可省略：每个 db.* 操作均可能返回 error，务必检查；多数连接失败的根本原因是忽略了 db.Ping() 的返回值。
• 资源清理：程序退出前应调用 db.Close() 释放连接池（本例未展示，生产环境必须添加）。

通过上述修正，你的 Go Web 应用能够稳定连接 MySQL，安全执行 CRUD 操作，彻底摆脱 nil pointer dereference 的 panic 困扰。