database

Database Package

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

✨ 特性

• 多数据库支持: MySQL、PostgreSQL、SQLite
• 配置验证: 完整的配置校验机制
• 连接池管理: 自动配置连接池参数
• 连接重试: 智能重试机制，支持指数退避和抖动
• 日志自定义: 支持文件日志输出
• 读写分离预留: 为未来扩展预留接口
• 线程安全: 支持并发访问
• 错误处理: 友好的错误信息

🚀 快速开始

基础使用 - 简化配置

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进行数据库操作
    // ... 你的业务逻辑
}

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

// 自定义重试配置
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
}

主要方法

🧪 测试

运行测试：

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