go-common/docs/factory.md

# 工厂工具文档

## 概述

工厂工具提供了从配置直接创建已初始化的客户端对象的功能，避免调用方重复实现创建逻辑。

## 功能特性

- 从配置直接创建已初始化的客户端对象
- 统一的工厂接口
- 避免调用方重复实现创建逻辑

## 使用方法

### 1. 从配置文件直接创建工厂（推荐）

```go
import "git.toowon.com/jimmy/go-common/factory"

// 直接传入配置文件路径，自动加载配置并创建工厂
fac, err := factory.NewFactoryFromFile("./config.json")
if err != nil {
    log.Fatal(err)
}

// 直接获取已初始化的对象
db, _ := fac.GetDatabase()        // 直接获取数据库对象
logger, _ := fac.GetLogger()      // 直接获取日志对象
emailClient, _ := fac.GetEmailClient()  // 直接获取邮件客户端
```

### 2. 从配置对象创建工厂

```go
import (
    "git.toowon.com/jimmy/go-common/config"
    "git.toowon.com/jimmy/go-common/factory"
)

// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
    log.Fatal(err)
}

// 创建工厂实例
fac := factory.NewFactory(cfg)
```

### 3. 获取数据库对象（已初始化，推荐）

```go
// 直接获取已初始化的数据库对象（*gorm.DB）
db, err := fac.GetDatabase()
if err != nil {
    log.Fatal(err)
}

// 直接使用，无需再创建连接
var users []User
db.Find(&users)
db.Create(&user)
```

### 4. 获取Redis客户端（已初始化，推荐）

```go
import (
    "context"
    "github.com/redis/go-redis/v9"
)

// 直接获取已初始化的Redis客户端对象
redisClient, err := fac.GetRedisClient()
if err != nil {
    log.Fatal(err)
}

// 直接使用，无需再创建连接
ctx := context.Background()
val, err := redisClient.Get(ctx, "key").Result()
if err != nil && err != redis.Nil {
    log.Printf("Redis error: %v", err)
} else if err == redis.Nil {
    fmt.Println("Key not found")
} else {
    fmt.Printf("Value: %s\n", val)
}
```

### 5. 获取邮件客户端（已初始化）

```go
// 直接获取已初始化的邮件客户端
emailClient, err := fac.GetEmailClient()
if err != nil {
    log.Fatal(err)
}

// 直接使用，无需再创建
err = emailClient.SendSimple(
    []string{"recipient@example.com"},
    "主题",
    "正文",
)
```

### 6. 获取短信客户端（已初始化）

```go
// 直接获取已初始化的短信客户端
smsClient, err := fac.GetSMSClient()
if err != nil {
    log.Fatal(err)
}

// 直接使用，无需再创建
resp, err := smsClient.SendSimple(
    []string{"13800138000"},
    map[string]string{"code": "123456"},
)
```

### 7. 获取日志记录器（已初始化）

```go
// 直接获取已初始化的日志记录器
logger, err := fac.GetLogger()
if err != nil {
    log.Fatal(err)
}

// 直接使用，无需再创建
logger.Info("Application started")
logger.Error("Error occurred: %v", err)
```

### 8. 完整示例

```go
package main

import (
    "log"
    
    "git.toowon.com/jimmy/go-common/config"
    "git.toowon.com/jimmy/go-common/factory"
)

func main() {
    // 加载配置
    cfg, err := config.LoadFromFile("./config.json")
    if err != nil {
        log.Fatal(err)
    }

    // 创建工厂
    fac := factory.NewFactory(cfg)

    // 获取邮件客户端（已初始化，可直接使用）
    emailClient, err := fac.GetEmailClient()
    if err != nil {
        log.Printf("Email client not available: %v", err)
    } else {
        // 直接使用
        err = emailClient.SendSimple(
            []string{"recipient@example.com"},
            "测试邮件",
            "这是测试内容",
        )
        if err != nil {
            log.Printf("Failed to send email: %v", err)
        }
    }

    // 获取短信客户端（已初始化，可直接使用）
    smsClient, err := fac.GetSMSClient()
    if err != nil {
        log.Printf("SMS client not available: %v", err)
    } else {
        // 直接使用
        resp, err := smsClient.SendSimple(
            []string{"13800138000"},
            map[string]string{"code": "123456"},
        )
        if err != nil {
            log.Printf("Failed to send SMS: %v", err)
        } else {
            log.Printf("SMS sent: %s", resp.RequestID)
        }
    }

    // 如果需要访问配置对象
    cfgObj := fac.GetConfig()
    dsn, _ := cfgObj.GetDatabaseDSN()
    log.Printf("Database DSN: %s", dsn)
}
```

## API 参考

### NewFactory(cfg *config.Config) *Factory

创建工厂实例。

**参数：**
- `cfg`: 配置对象

**返回：** 工厂实例

### NewFactoryFromFile(filePath string) (*Factory, error)

从配置文件直接创建工厂实例（便捷方法）。

**参数：**
- `filePath`: 配置文件路径

**返回：** 工厂实例和错误信息

**说明：** 这是推荐的使用方式，一步完成配置加载和工厂创建。

### (f *Factory) GetEmailClient() (*email.Email, error)

获取邮件客户端（已初始化）。

**返回：** 已初始化的邮件客户端对象和错误信息

**说明：** 如果邮件配置为nil，返回错误。

### (f *Factory) GetSMSClient() (*sms.SMS, error)

获取短信客户端（已初始化）。

**返回：** 已初始化的短信客户端对象和错误信息

**说明：** 如果短信配置为nil，返回错误。

### (f *Factory) GetLogger() (*logger.Logger, error)

获取日志记录器（已初始化）。

**返回：** 已初始化的日志记录器对象和错误信息

**说明：** 如果日志配置为nil，会使用默认配置创建。

### (f *Factory) GetDatabase() (*gorm.DB, error)

获取数据库连接对象（已初始化）。

**返回：** 已初始化的GORM数据库对象和错误信息

**说明：** 
- 支持MySQL、PostgreSQL、SQLite
- 自动配置连接池参数
- 数据库时间统一使用UTC时区

### (f *Factory) GetRedisClient() (*redis.Client, error)

获取Redis客户端对象（已初始化）。

**返回：** 已初始化的Redis客户端对象和错误信息

**说明：** 
- 自动处理所有配置检查和连接测试
- 自动设置默认值（连接池大小、超时时间等）
- 连接失败时会自动关闭客户端并返回错误
- 返回的客户端已通过Ping测试，可直接使用

### (f *Factory) GetRedisConfig() *config.RedisConfig

获取Redis配置（用于创建Redis客户端）。

**返回：** Redis配置对象（可能为nil）

**说明：** 
- 推荐使用 `GetRedisClient()` 方法直接获取已初始化的客户端
- 如果需要自定义创建Redis客户端，可以使用此方法获取配置

### (f *Factory) GetConfig() *config.Config

获取配置对象。

**返回：** 配置对象

## 优势

### 之前的方式（需要调用方实现）

```go
// 调用方需要自己实现创建逻辑
cfg, _ := config.LoadFromFile("./config.json")
dsn, _ := cfg.GetDatabaseDSN()
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
    log.Fatal(err)
}
// 配置连接池
sqlDB, _ := db.DB()
sqlDB.SetMaxOpenConns(100)
// 才能使用
db.Find(&users)
```

### 使用工厂方式（直接获取已初始化对象）

```go
// 方式1：直接从配置文件创建（最推荐）
fac, _ := factory.NewFactoryFromFile("./config.json")
db, _ := fac.GetDatabase()  // 直接获取已初始化的数据库对象
// 直接使用
db.Find(&users)

// 方式2：从配置对象创建
cfg, _ := config.LoadFromFile("./config.json")
fac := factory.NewFactory(cfg)
db, _ := fac.GetDatabase()  // 直接获取已初始化的数据库对象
// 直接使用
db.Find(&users)
```

## 注意事项

1. **配置检查**：工厂方法会自动检查配置是否存在，如果配置为nil会返回错误
2. **错误处理**：所有Get方法都可能返回错误，需要正确处理
3. **配置对象**：可以通过`GetConfig()`方法访问原始配置对象，获取其他配置信息

## 示例

完整示例请参考 `examples/factory_example.go`