424 lines
11 KiB
Markdown
424 lines
11 KiB
Markdown
# 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. Excel导出工具 (excel)
|
||
提供数据导出到Excel文件的功能，支持结构体切片、自定义格式化、多工作表等特性。
|
||
|
||
**功能特性**：
|
||
- 支持结构体切片自动导出
|
||
- 支持嵌套字段访问（如 "User.Name"）
|
||
- 支持自定义格式化函数
|
||
- 自动调整列宽和表头样式
|
||
- 支持导出到文件或HTTP响应
|
||
|
||
### 10. 工厂工具 (factory)
|
||
提供从配置文件直接创建已初始化客户端对象的功能，包括数据库、Redis、邮件、短信、日志、Excel等，避免调用方重复实现创建逻辑。
|
||
|
||
### 11. 日志工具 (logger)
|
||
提供统一的日志记录功能，支持多种日志级别和输出方式，使用Go标准库实现。
|
||
|
||
---
|
||
|
||
## 🎯 Factory 黑盒模式（核心设计）
|
||
|
||
**理念**：外部项目只需传递一个配置文件路径，直接使用黑盒方法，无需获取内部对象。
|
||
|
||
### 方法分类
|
||
|
||
| 类型 | 方法 | 使用方式 | 推荐度 |
|
||
|------|------|----------|--------|
|
||
| **黑盒方法（推荐）** | | | |
|
||
| 中间件 | `GetMiddlewareChain()` | 直接使用，可Append自定义中间件 | ⭐⭐⭐ |
|
||
| 日志 | `LogInfo()`, `LogError()` 等 | 直接调用，无需获取logger对象 | ⭐⭐⭐ |
|
||
| Redis | `RedisSet()`, `RedisGet()` 等 | 直接调用，覆盖常用操作 | ⭐⭐⭐ |
|
||
| 邮件 | `SendEmail()` | 直接调用 | ⭐⭐⭐ |
|
||
| 短信 | `SendSMS()` | 直接调用 | ⭐⭐⭐ |
|
||
| 存储 | `UploadFile()`, `GetFileURL()` | 直接调用 | ⭐⭐⭐ |
|
||
| Excel导出 | `ExportToExcel()`, `ExportToExcelFile()` | 直接调用 | ⭐⭐⭐ |
|
||
| **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")
|
||
|
||
// Excel导出
|
||
columns := []factory.ExportColumn{
|
||
{Header: "ID", Field: "ID", Width: 10},
|
||
{Header: "姓名", Field: "Name", Width: 20},
|
||
{Header: "邮箱", Field: "Email", Width: 30},
|
||
}
|
||
fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
|
||
|
||
// 数据库（高级功能）
|
||
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))
|
||
```
|
||
|
||
### 日期时间
|
||
**推荐方式：通过 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)
|
||
```
|
||
|
||
更多示例：[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！
|
||
|