# GoCommon - Go通用工具类库

这是一个Go语言开发的通用工具类库，为其他Go项目提供常用的工具方法集合。

## 功能模块

### 1. 数据库迁移工具 (migration)
提供数据库迁移功能，支持MySQL、PostgreSQL、SQLite等数据库。

### 2. 日期转换工具 (datetime)
提供日期时间转换功能，支持时区设定和多种格式转换。

### 3. HTTP Restful工具 (http)
提供HTTP请求/响应处理工具，包含标准化的响应结构、分页支持和HTTP状态码与业务状态码的分离。

### 4. 中间件工具 (middleware)
提供常用的HTTP中间件，包括CORS处理和时区管理。

### 5. 配置工具 (config)
提供从外部文件加载配置的功能，支持数据库、OSS、Redis、CORS、MinIO等配置。

### 6. 存储工具 (storage)
提供文件上传和查看功能，支持OSS和MinIO两种存储方式，并提供HTTP处理器。

### 7. 邮件工具 (email)
提供SMTP邮件发送功能，支持纯文本和HTML邮件，使用Go标准库实现。

### 8. 短信工具 (sms)
提供阿里云短信发送功能，支持模板短信和批量发送，使用Go标准库实现。

### 9. 工厂工具 (factory)
提供从配置文件直接创建已初始化客户端对象的功能，包括数据库、Redis、邮件、短信、日志等，避免调用方重复实现创建逻辑。

### 10. 日志工具 (logger)
提供统一的日志记录功能，支持多种日志级别和输出方式，使用Go标准库实现。

## 安装

### 1. 配置私有仓库（重要）

由于本项目使用私有 Git 仓库，需要先配置 `GOPRIVATE` 环境变量：

```bash
# 使用 go env 命令配置（推荐，永久生效）
go env -w GOPRIVATE=git.toowon.com

# 验证配置
go env GOPRIVATE
```

**详细配置说明请参考 [SETUP.md](./SETUP.md)**

**遇到问题？请查看 [故障排除指南](./TROUBLESHOOTING.md)**

### 2. 安装模块

```bash
# 安装最新版本（推荐用于开发）
go get git.toowon.com/jimmy/go-common@latest

# 安装特定版本（推荐用于生产）
go get git.toowon.com/jimmy/go-common@v1.0.0
```

**版本管理说明请参考 [VERSION.md](./VERSION.md)**

## 使用示例

详细的使用说明请参考各模块的文档：
- [数据库迁移工具文档](./docs/migration.md)
- [日期转换工具文档](./docs/datetime.md)
- [HTTP Restful工具文档](./docs/http.md)
- [中间件工具文档](./docs/middleware.md)
- [配置工具文档](./docs/config.md)
- [存储工具文档](./docs/storage.md)
- [邮件工具文档](./docs/email.md)
- [短信工具文档](./docs/sms.md)
- [工厂工具文档](./docs/factory.md)
- [日志工具文档](./docs/logger.md)

### 快速示例

#### 数据库迁移
```go
import "git.toowon.com/jimmy/go-common/migration"

migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
    Version: "20240101000001",
    Description: "create_users_table",
    Up: func(db *gorm.DB) error {
        return db.Exec("CREATE TABLE users ...").Error
    },
})
migrator.Up()
```

#### 日期转换
```go
import "git.toowon.com/jimmy/go-common/datetime"

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

#### HTTP响应（Handler黑盒模式）
```go
import (
    "net/http"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// 使用Handler（黑盒模式）
func GetUser(h *commonhttp.Handler) {
    id := h.GetQueryInt64("id", 0)  // 无需传递r
    h.Success(data)                  // 无需传递w
}

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

#### 中间件
```go
import (
    "git.toowon.com/jimmy/go-common/middleware"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// CORS + 时区中间件
chain := middleware.NewChain(
    middleware.CORS(),
    middleware.Timezone,
)
handler := chain.ThenFunc(yourHandler)

// 在Handler中获取时区
func handler(h *commonhttp.Handler) {
    timezone := h.GetTimezone()
}
```

#### 配置管理
```go
import "git.toowon.com/jimmy/go-common/config"

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

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

#### 文件上传和查看（推荐使用工厂黑盒模式）
```go
import (
    "context"
    "git.toowon.com/jimmy/go-common/factory"
)

fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()

// 黑盒模式（推荐，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")

// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期

// 或使用存储处理器（需要HTTP处理器时）
storage, _ := storage.NewStorage(storage.StorageTypeOSS, cfg)
uploadHandler := storage.NewUploadHandler(...)
```

#### 邮件发送（推荐使用工厂黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"

fac, _ := factory.NewFactoryFromFile("./config.json")

// 黑盒模式（推荐）
fac.SendEmail([]string{"user@example.com"}, "主题", "正文")
fac.SendEmail([]string{"user@example.com"}, "主题", "纯文本", "<h1>HTML内容</h1>")

// 或获取客户端对象（需要高级功能时）
emailClient, _ := fac.GetEmailClient()
emailClient.SendSimple(...)
```

#### 短信发送（推荐使用工厂黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"

fac, _ := factory.NewFactoryFromFile("./config.json")

// 黑盒模式（推荐）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})

// 或获取客户端对象（需要高级功能时）
smsClient, _ := fac.GetSMSClient()
smsClient.SendSimple(...)
```

#### 使用工厂（黑盒模式，推荐）
```go
import (
    "context"
    "git.toowon.com/jimmy/go-common/factory"
)

// 从配置文件创建工厂（最推荐）
fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()

// 日志（黑盒模式，直接调用）
fac.LogInfo("用户登录成功")
fac.LogError("登录失败: %v", err)

// 邮件发送（黑盒模式，直接调用）
fac.SendEmail([]string{"user@example.com"}, "验证码", "您的验证码是：123456")

// 短信发送（黑盒模式，直接调用）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})

// 文件上传（黑盒模式，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")

// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期

// Redis操作（黑盒模式，直接调用）
fac.RedisSet(ctx, "key", "value", time.Hour)
value, _ := fac.RedisGet(ctx, "key")
fac.RedisDelete(ctx, "key")

// 数据库（GORM已经很灵活，直接返回对象）
db, _ := fac.GetDatabase()
db.Find(&users)
```

更多示例请查看 [examples](./examples/) 目录。

## 版本管理

当前版本：**v1.0.0**

### 如何指定版本

在 `go.mod` 文件中指定版本：

```go
require (
    git.toowon.com/jimmy/go-common v1.0.0
)
```

或者使用命令行：

```bash
# 使用最新版本
go get git.toowon.com/jimmy/go-common@latest

# 使用特定版本
go get git.toowon.com/jimmy/go-common@v1.0.0
```

**详细版本管理说明请参考 [VERSION.md](./VERSION.md)**