# GoCommon - Go通用工具类库

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

**📖 快速链接**：
- [5分钟快速开始](./QUICKSTART.md)
- [数据库迁移指南](./MIGRATION.md) ⭐ 独立工具，零耦合，Docker友好
- [完整文档](./docs/README.md)

## 🌟 核心特性

### 🎯 **极简调用，减少80%重复代码**
- **工厂黑盒模式**：一个配置文件，搞定所有服务初始化
- **Handler黑盒模式**：统一的HTTP请求处理，无需重复传递 `w` 和 `r`
- **中间件链式调用**：一行代码组合多个中间件

### 🚀 **生产级特性，开箱即用**
- **异步日志**：不阻塞请求，高并发性能
- **Panic恢复**：自动捕获panic，防止服务崩溃
- **令牌桶限流**：保护API，防止滥用
- **时区自动处理**：统一管理时区，避免时间错乱

### 🔧 **灵活可扩展**
- **默认配置即可用**：传 `nil` 使用默认配置
- **完全可定制**：每个功能都支持自定义配置
- **无侵入设计**：可以独立使用任何模块

### 📦 **零外部依赖（核心功能）**
- email、sms 使用 Go 标准库实现
- 可选依赖：gorm（数据库）、redis、minio

## 功能模块

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

**🎯 独立工具，零耦合**：
- ✅ 编译成独立二进制：`go build -o bin/migrate cmd/migrate/main.go`
- ✅ 生产环境无需Go环境，只需二进制文件
- ✅ 与应用代码完全解耦，可独立部署和执行
- ✅ 支持宿主机和Docker，零额外配置

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

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

### 4. 中间件工具 (middleware)
提供生产级HTTP中间件，包括：
- **CORS** - 跨域资源共享
- **Timezone** - 时区处理
- **Logging** - 请求日志记录（支持异步）
- **Recovery** - Panic恢复，防止服务崩溃
- **RateLimit** - 请求限流（令牌桶算法）
- **Chain** - 中间件链式组合

### 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标准库实现。

---

## 🎯 Factory 黑盒模式（核心设计）

**理念**：外部项目只需传递一个配置文件路径，直接使用黑盒方法，无需获取内部对象。

### 方法分类

| 类型 | 方法 | 使用方式 | 推荐度 |
|------|------|----------|--------|
| **黑盒方法（推荐）** | | | |
| 中间件 | `GetMiddlewareChain()` | 直接使用，可Append自定义中间件 | ⭐⭐⭐ |
| 日志 | `LogInfo()`, `LogError()` 等 | 直接调用，无需获取logger对象 | ⭐⭐⭐ |
| Redis | `RedisSet()`, `RedisGet()` 等 | 直接调用，覆盖常用操作 | ⭐⭐⭐ |
| 邮件 | `SendEmail()` | 直接调用 | ⭐⭐⭐ |
| 短信 | `SendSMS()` | 直接调用 | ⭐⭐⭐ |
| 存储 | `UploadFile()`, `GetFileURL()` | 直接调用 | ⭐⭐⭐ |
| **Get方法（高级功能）** | | | |
| 数据库 | `GetDatabase()` | 返回GORM对象，用于复杂查询 | ⭐⭐ |
| Redis高级 | `GetRedisClient()` | 返回Redis客户端，用于Hash/List/Set等 | ⭐ |
| Logger高级 | `GetLogger()` | 返回Logger对象，用于Close等 | ⭐ |

### 使用示例

```go
// 创建工厂（只需配置文件路径）
fac, _ := factory.NewFactoryFromFile("config.json")

// ====== 推荐使用黑盒方法 ======
fac.LogInfo("用户登录")
fac.RedisSet(ctx, "key", "value", time.Hour)
fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
chain := fac.GetMiddlewareChain()

// ====== 仅在需要高级功能时获取对象 ======
db, _ := fac.GetDatabase()  // 数据库操作复杂，使用GORM
db.Find(&users)

client, _ := fac.GetRedisClient()  // Redis高级操作
client.HSet(ctx, "user:1", "name", "Alice")
```

---

## 安装

### 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)**

---

## 📚 文档导航

- **[快速开始指南](./QUICKSTART.md)** ⭐ - 5分钟快速上手
- [完整文档](./docs/README.md) - 所有模块详细文档
- [故障排除](./TROUBLESHOOTING.md) - 常见问题解决
- [版本管理](./VERSION.md) - 版本发布说明

---

## 快速开始

### 1. 创建配置文件 `config.json`

```json
{
    "database": {
        "type": "mysql",
        "host": "localhost",
        "port": 3306,
        "user": "root",
        "password": "password",
        "database": "mydb"
    },
    "redis": {
        "host": "localhost",
        "port": 6379
    },
    "logger": {
        "level": "info",
        "output": "both",
        "filePath": "./logs/app.log",
        "async": true
    }
}
```

### 2. 使用工厂黑盒模式（最简单，推荐）⭐

```go
package main

import (
    "context"
    "net/http"
    "time"
    
    "git.toowon.com/jimmy/go-common/factory"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

func main() {
    // 只需传入配置文件路径
    fac, _ := factory.NewFactoryFromFile("config.json")
    
    // 获取配置好的中间件链（黑盒）
    chain := fac.GetMiddlewareChain()
    
    // （可选）添加自定义中间件
    chain.Append(yourAuthMiddleware)
    
    // 注册路由
    http.Handle("/api/hello", chain.ThenFunc(handleHello))
    http.ListenAndServe(":8080", nil)
}

func handleHello(w http.ResponseWriter, r *http.Request) {
    h := commonhttp.NewHandler(w, r)
    fac, _ := factory.NewFactoryFromFile("config.json")
    ctx := context.Background()
    
    // 使用黑盒方法（无需获取对象）
    fac.LogInfo("处理请求: /api/hello")
    fac.RedisSet(ctx, "last_visit", time.Now().String(), time.Hour)
    
    h.Success(map[string]interface{}{
        "message": "Hello!",
        "timezone": h.GetTimezone(),
    })
}
```

### 3. 运行项目

```bash
go run main.go
# 访问 http://localhost:8080/api/hello
```

## 核心功能示例

详细文档请参考：[完整文档](./docs/README.md) | [快速开始](./QUICKSTART.md)

### 数据库迁移
```bash
# 编译独立工具
go build -o bin/migrate cmd/migrate/main.go

# 执行迁移
./bin/migrate up                              # 默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status                          # 查看状态
```

**详细说明**：[数据库迁移指南](./MIGRATION.md) ⭐

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

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

// 中间件
chain := fac.GetMiddlewareChain()
chain.Append(yourAuthMiddleware)  // 添加自定义中间件

// 日志
fac.LogInfo("用户登录成功")

// Redis
fac.RedisSet(ctx, "key", "value", time.Hour)

// 邮件/短信
fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})

// 文件上传
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")

// 数据库（高级功能）
db, _ := fac.GetDatabase()
db.Find(&users)
```

### HTTP处理器
```go
import commonhttp "git.toowon.com/jimmy/go-common/http"

func GetUser(h *commonhttp.Handler) {
    id := h.GetQueryInt64("id", 0)
    h.Success(data)
}

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

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

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

更多示例：[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)**

## 最佳实践

### 生产环境配置
```json
{
    "logger": {
        "async": true,           // 开启异步日志
        "bufferSize": 1000
    },
    "database": {
        "maxOpenConns": 100,     // 连接池配置
        "maxIdleConns": 10,
        "connMaxLifetime": 3600
    },
    "rateLimit": {
        "enable": true,          // 开启限流
        "rate": 100,
        "period": 60,
        "byIP": true
    }
}
```

### 使用建议
- ✅ 使用工厂黑盒模式，减少重复代码
- ✅ 生产环境开启异步日志和限流
- ✅ 配置Recovery中间件防止panic
- ✅ 明确指定CORS允许的源
- ❌ 避免在循环中创建logger
- ❌ 避免使用同步日志记录大量日志

## 故障排除

常见问题请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

MIT License

## 联系方式

- 作者：Jimmy
- 邮箱：jimmy@toowon.com
- 项目地址：git.toowon.com/jimmy/go-common

---

⭐ 如果这个项目对你有帮助，请给个 Star！