重构项目的实现,优化使用方法与使用逻辑
This commit is contained in:
438
README.md
438
README.md
@@ -1,424 +1,56 @@
|
||||
# GoCommon - Go通用工具类库
|
||||
# GoCommon - Go 通用工具类库
|
||||
|
||||
这是一个Go语言开发的通用工具类库，为其他Go项目提供常用的工具方法集合。
|
||||
供其他 Go 项目引用的通用工具集合。业务项目对接请直接阅读：
|
||||
|
||||
**📖 快速链接**：
|
||||
- [5分钟快速开始](./QUICKSTART.md)
|
||||
- [数据库迁移指南](./MIGRATION.md) ⭐ 独立工具，零耦合，Docker友好
|
||||
- [完整文档](./docs/README.md)
|
||||
**[业务项目对接操作手册（INTEGRATION.md）](./INTEGRATION.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)
|
||||
提供文件上传和查看功能，支持本地文件夹（Local）、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等 | ⭐ |
|
||||
| 存储高级 | `GetStorage()` | 返回Storage对象，用于Delete/Exists/GetObject等 | ⭐ |
|
||||
|
||||
### 使用示例
|
||||
|
||||
```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")
|
||||
```
|
||||
|
||||
---
|
||||
git.toowon.com/jimmy/go-common
|
||||
```
|
||||
|
||||
## 安装
|
||||
|
||||
### 1. 配置私有仓库（重要）
|
||||
|
||||
由于本项目使用私有 Git 仓库，需要先配置 `GOPRIVATE` 环境变量：
|
||||
|
||||
```bash
|
||||
# 使用 go env 命令配置（推荐，永久生效）
|
||||
go env -w GOPRIVATE=git.toowon.com
|
||||
|
||||
# 验证配置
|
||||
go env GOPRIVATE
|
||||
go get git.toowon.com/jimmy/go-common@v2.0.0
|
||||
```
|
||||
|
||||
**详细配置说明请参考 [SETUP.md](./SETUP.md)**
|
||||
## 设计概要
|
||||
|
||||
**遇到问题？请查看 [故障排除指南](./TROUBLESHOOTING.md)**
|
||||
- **Factory**：入口，启动时初始化一次，按需 getter 获取模块对象（DB、Redis、Logger 等）
|
||||
- **各模块包**：能力在对象方法上（`log.Info()`、`store.Upload()`）
|
||||
- **http 包**：统一 HTTP 出参（Response / PageData / Handler）
|
||||
- **migration**：独立 CLI 或 Factory 执行 SQL 迁移
|
||||
- **tools**：无状态工具函数，直接 import
|
||||
|
||||
### 2. 安装模块
|
||||
## 功能模块
|
||||
|
||||
```bash
|
||||
# 安装最新版本（推荐用于开发）
|
||||
go get git.toowon.com/jimmy/go-common@latest
|
||||
| 模块 | 包路径 | 说明 |
|
||||
|------|--------|------|
|
||||
| 配置 | `config` | JSON 配置加载 |
|
||||
| 工厂 | `factory` | 统一入口与 lazy getter |
|
||||
| HTTP | `http` | 请求解析、统一响应 |
|
||||
| 中间件 | `middleware` | CORS、日志、Recovery、限流、语种、时区 |
|
||||
| 工具 | `tools` | 时间、加密、金额、类型转换 |
|
||||
| 日志 | `logger` | 异步日志 |
|
||||
| 存储 | `storage` | Local / OSS / MinIO |
|
||||
| 邮件 / 短信 | `email` / `sms` | SMTP、阿里云短信 |
|
||||
| Excel | `excel` | 数据导出 |
|
||||
| 国际化 | `i18n` | 多语言消息 |
|
||||
| 迁移 | `migration` | SQL 版本管理 |
|
||||
|
||||
# 安装特定版本（推荐用于生产）
|
||||
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
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [INTEGRATION.md](./INTEGRATION.md) | 业务项目对接操作手册 |
|
||||
| [VERSION.md](./VERSION.md) | 版本管理与发布 |
|
||||
| [templates/](./templates/) | migrate 等脚手架模板 |
|
||||
| [config/example.json](./config/example.json) | 配置文件示例 |
|
||||
| [examples/](./examples/) | 代码示例 |
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
|
||||
## 联系方式
|
||||
|
||||
- 作者：Jimmy
|
||||
- 邮箱：jimmy@toowon.com
|
||||
- 项目地址：git.toowon.com/jimmy/go-common
|
||||
|
||||
---
|
||||
|
||||
⭐ 如果这个项目对你有帮助，请给个 Star！
|
||||
|
||||
|
||||
Reference in New Issue
Block a user