# GoCommon 工具类库文档

## 目录

- [数据库迁移工具](./migration.md) - 数据库版本管理和迁移
  - [完整使用指南](../MIGRATION.md) ⭐ - 独立工具，零耦合，Docker友好
- [日期转换工具](./datetime.md) - 日期时间处理和时区转换
- [HTTP Restful工具](./http.md) - HTTP请求响应处理和分页
- [中间件工具](./middleware.md) - 生产级HTTP中间件（CORS、时区、日志、Recovery、限流）
- [配置工具](./config.md) - 外部配置文件加载和管理
- [存储工具](./storage.md) - 文件上传和查看（OSS、MinIO）
- [邮件工具](./email.md) - SMTP邮件发送
- [短信工具](./sms.md) - 阿里云短信发送
- [工厂工具](./factory.md) - 从配置直接创建已初始化客户端对象
- [日志工具](./logger.md) - 统一的日志记录功能

## 快速开始

### 安装

```bash
go get git.toowon.com/jimmy/go-common
```

### 使用示例

#### 数据库迁移（独立工具，零耦合）

```bash
# 1. 复制模板：templates/migrate/main.go -> cmd/migrate/main.go
# 2. 创建迁移文件：migrations/20240101000001_create_users.sql

# 3. 开发环境
go run cmd/migrate/main.go up

# 4. 生产环境（编译后使用，推荐）
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up                              # 使用默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status                          # 查看状态

# 5. Docker（挂载配置，修改无需重启）
# docker-compose.yml:
# volumes:
#   - ./config.json:/app/config.json:ro
# command: sh -c "./migrate up && ./server"
```

**迁移文件示例**（`migrations/20240101000001_create_users.sql`）：
```sql
CREATE TABLE users (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
```

**优势**：独立工具，零耦合，支持命令行参数，Docker友好

详细说明：[MIGRATION.md](../MIGRATION.md)

#### 日期转换

**推荐方式：通过 factory 使用（黑盒模式）**

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

fac, _ := factory.NewFactoryFromFile("config.json")
now := fac.Now("Asia/Shanghai")
str := fac.FormatDateTime(now)
```

**或者直接使用 tools 包：**

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

tools.SetDefaultTimeZone(tools.AsiaShanghai)
now := tools.Now()
str := tools.FormatDateTime(now)
```

#### HTTP响应（Factory黑盒模式，推荐）

```go
import (
    "net/http"
    "git.toowon.com/jimmy/go-common/factory"
    "git.toowon.com/jimmy/go-common/tools"
)

func GetUser(w http.ResponseWriter, r *http.Request) {
    fac, _ := factory.NewFactoryFromFile("config.json")
    
    // 获取查询参数（使用类型转换方法）
    id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
    
    // 返回成功响应
    fac.Success(w, data)
}

http.HandleFunc("/user", GetUser)
```

#### 中间件（生产级配置）

```go
import (
    "time"
    "git.toowon.com/jimmy/go-common/middleware"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// 完整的中间件链
chain := middleware.NewChain(
    middleware.Recovery(nil),   // Panic恢复
    middleware.Logging(nil),    // 请求日志
    middleware.RateLimitByIP(100, time.Minute), // 限流
    middleware.CORS(nil),       // CORS
    middleware.Timezone,        // 时区
)

handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
    h := commonhttp.NewHandler(w, r)
    timezone := h.GetTimezone()
    h.Success(data)
})
```

#### 配置管理

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

// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")

// 获取各种配置
dsn, _ := cfg.GetDatabaseDSN()
redisAddr := cfg.GetRedisAddr()
corsConfig := cfg.GetCORS()
```

## 版本

v1.0.0

## 许可证

MIT