database

Database Package

基于 GORM 的数据库封装，提供简洁、可扩展、易用的数据库操作接口。

✨ 特性

• 多数据库支持: MySQL、PostgreSQL、SQLite
• 配置验证: 完整的配置校验机制
• 连接池管理: 自动配置连接池参数
• 连接重试: 智能重试机制，支持指数退避和抖动
• 日志自定义: 支持文件日志输出
• 读写分离预留: 为未来扩展预留接口
• 线程安全: 支持并发访问
• 错误处理: 友好的错误信息
• GORM Gen 兼容: 直接将 *gorm.DB 注入生成代码，事务/上下文保持一致

🚀 快速开始

基础使用 - 简化配置

package main

import (
    "go-kit/pkg/database"
    "gorm.io/gorm"
)

func main() {
    // 1. 使用Builder模式创建配置
    config := database.NewConfigBuilder().
        SQLite(":memory:").
        Build()

    // 2. 创建数据库连接
    db, err := database.New(config)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // 3. 获取GORM实例
    gormDB := db.GetDB()
    
    // 4. 使用GORM进行数据库操作
    // ... 你的业务逻辑
}

与 gorm/gen 集成

// 假设生成的 query 包路径为 "yourapp/internal/query"
import (
    "context"
    "database/sql"

    "github.com/tsopia/go-kit/database"
    "gorm.io/gorm"
    "yourapp/internal/model" // gorm/gen 生成的 model 包路径
    "yourapp/internal/query" // gorm/gen 生成的 query 包路径
)

func main() {
    cfg := database.NewConfigBuilder().
        MySQL("127.0.0.1", "root", "password", "app").
        Build()

    db, err := database.New(cfg)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // 将封装后的 *gorm.DB 传给 gorm/gen 生成的 query 层
    q := query.Use(db.GetDB())

    ctx := context.Background()

    // 在同一个事务中执行多张表的操作（gorm/gen 默认 Transaction 基于 *gorm.DB）
    err = db.TransactionWithContext(ctx, func(tx *gorm.DB) error {
        // 将事务会话透传给生成的 query（Use 会克隆 tx，WithContext 传递 ctx）
        qtx := query.Use(tx).WithContext(ctx)

        if _, err := qtx.User.Create(&model.User{Name: "foo"}); err != nil {
            return err
        }

        _, err := qtx.Account.Create(&model.Account{UserID: 1, Balance: 100})
        return err
    })
    if err != nil {
        panic(err)
    }
}

如果需要指定隔离级别/读写模式，可使用 BeginTx 显式开启事务并传入 sql.TxOptions：

tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable, ReadOnly: false})
if err != nil {
    panic(err)
}
qtx := query.Use(tx).WithContext(ctx)
// ...业务 SQL...
if err := tx.Commit().Error; err != nil {
    _ = tx.Rollback()
    panic(err)
}

封装接口与受控逃逸

Database 同时实现了 database.DB 接口，优先使用封装好的方法，必要时再通过受控逃逸访问底层 *gorm.DB：

cfg := database.NewConfigBuilder().MySQL("127.0.0.1", "root", "pwd", "app").Build()

db, err := database.NewWithOptions(
    cfg,
    database.WithLogger(myLogger),
    database.WithHooks(database.Hooks{BeforeProbe: func(ctx context.Context) error {
        // 探针前的自定义检查，例如 feature flag
        return nil
    }}),
)
if err != nil {
    panic(err)
}
defer db.Close()

// 优先使用封装接口
if err := db.Exec(ctx, "UPDATE users SET last_seen = NOW() WHERE id = ?", userID); err != nil {
    panic(err)
}
var u userModel
if err := db.Query(ctx, &u, "SELECT * FROM users WHERE id = ?", userID); err != nil {
    panic(err)
}

// 需要 gorm 高级能力时，再受控获取
gormDB := db.Raw()

// 需要专用连接或 driver 原生能力（如 PostgreSQL LISTEN/NOTIFY、pgvector 扩展）
sqlDB, err := db.SQLDB()
if err != nil {
    panic(err)
}
defer sqlDB.Close()

组件化职责（Phase 1）

数据库封装已拆分为可替换的职责组件，便于按需扩展或接入自定义实现：

• Connector：负责配置验证、连接建立与重试、命名策略以及连接池参数配置。
• Executor：承载 Exec / Query / Tx / BeginTx 等常规执行能力。
• HealthChecker：实现 Ping / HealthCheck / HealthCheckWithContext，串联探针钩子。

默认实现随 database.New/NewWithOptions 一起注入；若需要接入自定义拨号器或观测增强，可以通过 WithConnector、WithExecutor、WithHealthChecker 选项替换对应组件，无需修改业务代码。

命名与兼容约定

• GetDB() 与 Raw() 属于公开 API，保持向后兼容。
• 内部私有辅助方法可重构或去重，但不应改变导出方法行为与线程安全语义。

PostgreSQL 高级能力示例

LISTEN/NOTIFY（类消息队列）

GORM 不直接暴露异步通知 API，但可以通过 SQLDB() 拿到底层连接，并结合 pgx stdlib 驱动访问原生 *pgconn.PgConn：

import (
    "context"
    "log"

    "github.com/jackc/pgx/v5/pgconn"
    "github.com/jackc/pgx/v5/stdlib"
    "github.com/tsopia/go-kit/database"
)

db, _ := database.New(database.NewConfigBuilder().
    PostgreSQL("127.0.0.1", "postgres", "pwd", "app").Build())
ctx := context.Background()

sqlDB, _ := db.SQLDB()
conn, _ := sqlDB.Conn(ctx)
defer conn.Close()

var pgConn *pgconn.PgConn
_ = conn.Raw(func(dc interface{}) error {
    stdConn, ok := dc.(*stdlib.Conn)
    if !ok {
        return fmt.Errorf("unexpected driver conn %T", dc)
    }
    pgConn = stdConn.Conn()
    return nil
})

if _, err := pgConn.Exec(ctx, "LISTEN events").ReadAll(); err != nil {
    log.Fatal(err)
}
for {
    notif, err := pgConn.WaitForNotification(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("channel=%s payload=%s", notif.Channel, notif.Payload)
}

pgvector 嵌入向量

pgvector 需通过扩展启用，创建列时可直接使用 Raw()/GORM 声明字段类型：

import "github.com/pgvector/pgvector-go"

// 启用扩展
_ = db.Raw().Exec("CREATE EXTENSION IF NOT EXISTS vector").Error

// 定义模型
type Item struct {
    ID        int64
    Embedding pgvector.Vector `gorm:"type:vector(3)"`
}

// 相似度查询
var items []Item
err := db.Raw().
    Where("embedding <-> ? < 0.3", pgvector.NewVector([]float32{0.1, 0.2, 0.3})).
    Find(&items).Error

高级配置 - 自定义重试策略

// 自定义重试配置
config := &database.Config{
    Driver:   "mysql",
    Host:     "localhost",
    Port:     3306,
    Username: "root",
    Password: "password",
    Database: "test",
    
    // 自定义重试策略
    RetryEnabled:       true,
    RetryMaxAttempts:   5,                    // 最大重试5次
    RetryInitialDelay:  500 * time.Millisecond, // 初始延迟0.5秒
    RetryMaxDelay:      10 * time.Second,      // 最大延迟10秒
    RetryBackoffFactor: 1.5,                   // 退避因子1.5
    RetryJitterEnabled: true,                  // 启用抖动
}

db, err := database.New(config)
if err != nil {
    log.Fatal(err)
}
defer db.Close()

禁用重试

// 禁用重试机制
config := &database.Config{
    Driver:   "sqlite",
    Database: "test.db",
    
    // 禁用重试
    RetryEnabled:     false,
    RetryMaxAttempts: 1, // 或者设置为1
}

不同数据库的简化配置

// MySQL - 最简单
config := database.NewConfigBuilder().
    MySQL("localhost", "root", "password", "test_db").
    Build()

// PostgreSQL - 带高级选项
config := database.NewConfigBuilder().
    PostgreSQL("localhost", "postgres", "password", "test_db").
    WithPort(5432).
    WithSSLMode("disable").
    WithLogFile("/tmp/pg.log").
    Build()

// SQLite - 内存数据库
config := database.NewConfigBuilder().
    SQLite(":memory:").
    Build()

高级配置

config := &database.Config{
    Driver:          "mysql",
    Host:            "localhost",
    Port:            3306,
    Username:        "root",
    Password:        "password",
    Database:        "test_db",
    Charset:         "utf8mb4",
    Timezone:        "Local",
    
    // 连接池配置
    MaxIdleConns:    10,
    MaxOpenConns:    100,
    ConnMaxLifetime: time.Hour,
    ConnMaxIdleTime: 10 * time.Minute,
    
    // 日志配置
    LogLevel:        "info",
    SlowThreshold:   200 * time.Millisecond,
    Colorful:        true,
    LogOutput:       "file:///var/log/db.log", // 文件日志
    
    // 命名策略
    TablePrefix:     "app_",
    SingularTable:   true,
    
    // 其他配置
    DisableForeignKey: false,
    PrepareStmt:       true,
    DryRun:            false,
}

📋 配置说明

基础配置

连接池配置

日志配置

重试配置

🔧 API 参考

Config

type Config struct {
    // 基础配置
    Driver   string
    Host     string
    Port     int
    Username string
    Password string
    Database string
    Charset  string
    SSLMode  string
    Timezone string
    
    // 连接池配置
    MaxIdleConns    int
    MaxOpenConns    int
    ConnMaxLifetime time.Duration
    ConnMaxIdleTime time.Duration
    
    // 日志配置
    LogLevel      string
    SlowThreshold time.Duration
    Colorful      bool
    LogOutput     string
    
    // 重试配置
    RetryEnabled       bool
    RetryMaxAttempts   int
    RetryInitialDelay  time.Duration
    RetryMaxDelay      time.Duration
    RetryBackoffFactor float64
    RetryJitterEnabled bool
    
    // 读写分离配置
    ReadReplicas  []ReplicaConfig
    WriteReplicas []ReplicaConfig
    
    // 其他配置
    TablePrefix       string
    SingularTable     bool
    DisableForeignKey bool
    PrepareStmt       bool
    DryRun            bool
    Plugins           []string
    Hooks             map[string]string
}

Database

type Database struct {
    config *Config
    db     *gorm.DB
    mu     sync.RWMutex

    connector     Connector
    executor      Executor
    healthChecker HealthChecker
}

主要方法

高级定制：需要替换拨号/执行/探针逻辑时，可通过 WithConnector、WithExecutor、WithHealthChecker 选项注入自定义实现，无需改动业务调用方。

🧪 测试

运行测试：

go test ./pkg/database -v

测试覆盖：

• ✅ 配置验证
• ✅ 数据库连接
• ✅ CRUD操作
• ✅ 事务处理
• ✅ 错误处理
• ✅ 并发访问

📝 示例

简化配置示例

完整示例请参考：examples/database-simple/main.go

传统配置示例

完整示例请参考：examples/database-optimized/main.go

🎯 配置简化对比

传统方式 vs Builder模式

传统方式 (20+ 行):

config := &database.Config{
    Driver:          "mysql",
    Host:            "localhost",
    Port:            3306,
    Username:        "root",
    Password:        "password",
    Database:        "test_db",
    Charset:         "utf8mb4",
    Timezone:        "Local",
    MaxIdleConns:    10,
    MaxOpenConns:    100,
    ConnMaxLifetime: time.Hour,
    ConnMaxIdleTime: 10 * time.Minute,
    LogLevel:        "info",
    SlowThreshold:   200 * time.Millisecond,
    Colorful:        true,
    TablePrefix:     "app_",
    SingularTable:   true,
    PrepareStmt:     true,
    DryRun:          false,
}

Builder模式 (5-10 行):

config := database.NewConfigBuilder().
    MySQL("localhost", "root", "password", "test_db").
    WithConnectionPool(10, 100, time.Hour, 10*time.Minute).
    WithLogging("info", 200*time.Millisecond, true).
    WithTablePrefix("app_").
    Build()

优势总结

🔄 优化历史

v1.2.0 (当前版本) - 配置简化

重大改进：

• ✅ 配置简化: 引入Builder模式，配置代码减少70%
• ✅ 学习成本降低: 从20+字段简化为链式调用
• ✅ 错误率降低: 类型安全的Builder API
• ✅ 可读性提升: 配置意图一目了然

新增功能：

• NewConfigBuilder() - 配置构建器
• MySQL()/PostgreSQL()/SQLite() - 数据库类型方法
• WithXXX() - 链式配置方法
• 合理的默认值，无需记忆所有参数

v1.1.0 (历史版本)

优化内容：

• ✅ 清理未使用的 ConnectionPool 接口
• ✅ 改进错误信息友好性
• ✅ 添加副本配置验证
• ✅ 改进SQLite路径处理
• ✅ 添加日志自定义支持
• ✅ 完善测试用例

新增功能：

• 支持文件日志输出 (LogOutput: "file:///path/to/log")
• SQLite路径验证和目录检查
• 更详细的错误信息提示
• 完整的配置验证机制

🚨 注意事项

1. 资源管理: 使用完毕后务必调用 Close() 方法
2. 并发安全: 支持并发访问，但建议在应用层做适当控制
3. 配置验证: 建议在创建连接前调用 config.Validate() 进行预校验
4. 日志输出: 文件日志路径需要确保目录存在且有写权限

🤝 贡献

欢迎提交 Issue 和 Pull Request！

�� 许可证

MIT License