本文介绍如何在 Gin 框架驱动的多包 REST API 中，通过独立 database 包统一管理并导出 *sql.DB 实例，实现线程安全、清晰可控的数据库连接复用。
本文介绍如何在 gin 框架驱动的多包 rest api 中，通过独立 database 包统一管理并导出 `*sql.db` 实例，实现线程安全、清晰可控的数据库连接复用。
在 Go 语言开发中，*sql.DB 本身并非一个“单次连接”，而是一个线程安全的连接池句柄。官方文档明确指出：它被设计为长期存活、被多个 goroutine 并发复用——因此，全局共享一个 *sql.DB 实例不仅是可行的，更是推荐的最佳实践。然而，当项目按功能拆分为多个包（如 user、order、product）时，直接在 main 包中定义全局变量会导致其他包无法访问；若在各业务包中重复初始化，则违背连接池初衷，还可能引发资源泄漏或配置不一致。
✅ 推荐方案：创建专用 database 包封装连接
最清晰、可维护性最强的方式是将数据库初始化逻辑与连接变量提取为独立包（例如 database），该包仅负责连接的创建、配置（如 SetMaxOpenConns/SetMaxIdleConns）和暴露。其他业务包通过标准 import 显式依赖它，语义明确，无隐式耦合。
以下为最小可行实现：
// database/database.go
package database
import (
"database/sql"
_ "github.com/lib/pq" // PostgreSQL driver
)
var DBCon *sql.DB // 导出的全局连接句柄
// Init 初始化数据库连接（建议调用一次）
func Init(connStr string) error {
var err error
DBCon, err = sql.Open("postgres", connStr)
if err != nil {
return err
}
// 可选：设置连接池参数（强烈建议）
DBCon.SetMaxOpenConns(25)
DBCon.SetMaxIdleConns(25)
DBCon.SetConnMaxLifetime(5 * 60 * time.Second) // 5分钟
// 验证连接可用性
if err = DBCon.Ping(); err != nil {
return err
}
return nil
}// main.go
package main
import (
"log"
"myApp/database"
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
// 在应用启动早期完成数据库初始化
if err := database.Init("user=myname dbname=dbname sslmode=disable"); err != nil {
log.Fatal("Failed to connect to database:", err)
}
defer database.DBCon.Close() // 程序退出前关闭连接池
r := gin.Default()
r.GET("/users", userHandler)
r.Run(":8080")
}// user/user.go
package user
import (
"database/sql"
"myApp/database"
"net/http"
"github.com/gin-gonic/gin"
)
func userHandler(c *gin.Context) {
rows, err := database.DBCon.Query("SELECT id, name FROM users LIMIT 10")
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
return
}
defer rows.Close()
// 处理结果...
c.JSON(http.StatusOK, gin.H{"message": "users fetched"})
}⚠️ 关键注意事项
- 不要在业务包中调用 sql.Open：这会导致多个独立连接池，浪费资源且难以监控；
- 务必调用 DBCon.Close()：虽非强制，但应在 main 函数退出前显式关闭，确保底层连接被释放；
- 避免在 init() 函数中初始化 DB：这会隐藏依赖关系，不利于测试和配置隔离；
- 环境配置应外部化：连接字符串建议从 os.Getenv 或配置文件读取，而非硬编码；
- 考虑使用依赖注入（进阶）：对于大型项目，可结合 wire 或 fx 等工具实现更灵活的依赖管理，但对多数中型 API，上述包级共享已足够简洁可靠。
通过这种结构，你既保留了 Go 的包组织优势，又实现了连接池的真正复用——每个包都明确知道自己依赖数据库，且共享同一套连接生命周期管理逻辑。
