jimmy/go-common
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

调整工厂模式的方法

Browse Source
This commit is contained in:
Jimmy Xue
2025-12-05 00:07:15 +08:00
parent 0650feb0d2
commit 6146178111
15 changed files with 635 additions and 1039 deletions
Download Patch File Download Diff File Expand all files Collapse all files

516
README.md
View File

@@ -73,6 +73,50 @@
### 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. 配置私有仓库（重要）
@@ -141,53 +185,46 @@ go get git.toowon.com/jimmy/go-common@v1.0.0
}
```
### 2. 使用工厂模式（最简单，推荐）
### 2. 使用工厂黑盒模式（最简单，推荐）⭐
```go
package main
import (
"context"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func main() {
// 从配置文件创建工厂
fac, _ := factory.NewFactoryFromFile("./config.json")
// 只需传入配置文件路径
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取logger
logger, _ := fac.GetLogger()
defer logger.Close()
// 获取配置好的中间件链（黑盒）
chain := fac.GetMiddlewareChain()
// 配置中间件
chain := middleware.NewChain(
middleware.Recovery(&middleware.RecoveryConfig{Logger: logger}),
middleware.Logging(&middleware.LoggingConfig{Logger: logger}),
middleware.RateLimitByIP(100, time.Minute),
middleware.CORS(nil),
middleware.Timezone,
)
// （可选）添加自定义中间件
chain.Append(yourAuthMiddleware)
// 注册API路由
// 注册路由
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("Hello API called")
// 使用黑盒方法（无需获取对象）
fac.LogInfo("处理请求: /api/hello")
fac.RedisSet(ctx, "last_visit", time.Now().String(), time.Hour)
// 返回响应
h.Success(map[string]interface{}{
"message": "Hello, World!",
"message": "Hello!",
"timezone": h.GetTimezone(),
})
}
@@ -200,46 +237,64 @@ go run main.go
# 访问 http://localhost:8080/api/hello
```
## 使用示例
## 核心功能示例
详细的使用说明请参考各模块的文档：
- **[数据库迁移完整指南](./MIGRATION.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)
详细文档请参考：[完整文档](./docs/README.md) | [快速开始](./QUICKSTART.md)
### 快速示例
#### 数据库迁移（独立工具，零耦合）⭐
### 数据库迁移
```bash
# 1. 复制模板：templates/migrate/main.go -> cmd/migrate/main.go
# 2. 编译（生产环境推荐）
# 编译独立工具
go build -o bin/migrate cmd/migrate/main.go
# 3. 使用
./bin/migrate up # 使用默认配置
# 执行迁移
./bin/migrate up # 默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status # 查看状态
# 迁移文件：migrations/20240101000001_create_users.sql
# CREATE TABLE users (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
# Docker 中使用（挂载配置，修改无需重启）
# volumes:
# - ./config.json:/app/config.json:ro
# command: sh -c "./migrate up && ./server"
```
**详细说明**：[数据库迁移完整指南](./MIGRATION.md) 📖
**详细说明**：[数据库迁移指南](./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"
@@ -248,181 +303,7 @@ 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 (
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 方式1：简单配置（使用默认设置）
chain := middleware.NewChain(
middleware.Recovery(nil), // Panic恢复
middleware.Logging(nil), // 请求日志
middleware.RateLimit(nil), // 限流（100请求/分钟）
middleware.CORS(nil), // CORS（允许所有源）
middleware.Timezone, // 时区处理
)
http.Handle("/api", chain.ThenFunc(yourHandler))
// 方式2：生产级配置（推荐）
// 创建异步logger
myLogger, _ := logger.NewLogger(&config.LoggerConfig{
Level: "info",
Output: "both",
FilePath: "./logs/app.log",
Async: true, // 异步模式，不阻塞请求
})
chain := middleware.NewChain(
middleware.Recovery(&middleware.RecoveryConfig{
Logger: myLogger,
EnableStackTrace: true,
}),
middleware.Logging(&middleware.LoggingConfig{
Logger: myLogger,
SkipPaths: []string{"/health"},
}),
middleware.RateLimitByIP(100, time.Minute), // 100请求/分钟
middleware.CORS(nil),
middleware.Timezone,
)
// 在Handler中使用
func handler(h *commonhttp.Handler) {
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()
```
#### 文件上传和查看（推荐使用工厂黑盒模式）
```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")
// 数据库（黑盒模式，获取已初始化对象）
db, _ := fac.GetDatabase()
db.Find(&users)
// Redis客户端（黑盒模式，获取已初始化对象）
redisClient, _ := fac.GetRedisClient()
redisClient.HGet(ctx, "key", "field").Result()
```
更多示例请查看 [examples](./examples/) 目录。
更多示例：[examples目录](./examples/)
## 版本管理
@@ -450,175 +331,40 @@ go get git.toowon.com/jimmy/go-common@v1.0.0
**详细版本管理说明请参考 [VERSION.md](./VERSION.md)**
## 设计理念
### 1. 黑盒模式 - 减少重复代码
**问题**：传统方式需要在每个项目中重复编写初始化代码
```go
// ❌ 传统方式 - 需要在每个项目中重复
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
sqlDB, _ := db.DB()
sqlDB.SetMaxOpenConns(100)
sqlDB.SetMaxIdleConns(10)
// ... 更多配置
```
**解决**：工厂黑盒模式 - 配置文件搞定一切
```go
// ✅ 黑盒模式 - 一行代码搞定
db, _ := factory.NewFactoryFromFile("config.json").GetDatabase()
```
### 2. Handler模式 - 统一请求处理
**问题**：每个处理器都要传递 `w` 和 `r`
```go
// ❌ 传统方式
func GetUser(w http.ResponseWriter, r *http.Request) {
id := r.URL.Query().Get("id")
json.NewEncoder(w).Encode(data)
}
```
**解决**：Handler封装 - 简洁优雅
```go
// ✅ Handler模式
func GetUser(h *commonhttp.Handler) {
id := h.GetQueryInt64("id", 0)
h.Success(data)
}
```
### 3. 中间件链 - 灵活组合
**问题**：中间件嵌套难以维护
```go
// ❌ 传统方式 - 嵌套地狱
handler := corsMiddleware(
timezoneMiddleware(
loggingMiddleware(
yourHandler
)
)
)
```
**解决**：链式调用 - 清晰明了
```go
// ✅ 链式组合
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
middleware.Logging(nil),
)
handler := chain.ThenFunc(yourHandler)
```
## 最佳实践
### ✅ 推荐做法
1. **使用工厂模式**：通过配置文件统一管理所有服务
2. **使用异步日志**：生产环境开启 `Async: true`
3. **配置Recovery中间件**：防止panic导致服务崩溃
4. **合理设置限流**：根据实际业务设置限流阈值
5. **使用时区中间件**：统一管理时区，避免时间错乱
### ❌ 避免做法
1. **不要在循环中创建logger**：使用全局logger或工厂模式
2. **不要跳过健康检查日志**：高频接口应该配置 `SkipPaths`
3. **不要使用同步日志记录大量日志**：高并发场景使用异步模式
4. **不要在生产环境使用 `CORS: *`**：明确指定允许的源
## 性能优化建议
### 日志优化
```go
// ✅ 异步模式 - 高并发场景
loggerConfig := &config.LoggerConfig{
Async: true, // 异步写入
BufferSize: 1000, // 缓冲区大小
}
// ✅ 跳过高频接口
loggingConfig := &middleware.LoggingConfig{
SkipPaths: []string{"/health", "/metrics", "/ping"},
}
```
### 中间件顺序优化
```go
// ✅ 推荐顺序（从外到内）
chain := middleware.NewChain(
middleware.Recovery(cfg), // 1. 最外层捕获panic
middleware.Logging(cfg), // 2. 记录所有请求
middleware.RateLimit(cfg), // 3. 限流保护
middleware.CORS(cfg), // 4. CORS处理
middleware.Timezone, // 5. 时区处理
)
```
### 数据库连接池优化
### 生产环境配置
```json
{
"logger": {
"async": true, // 开启异步日志
"bufferSize": 1000
},
"database": {
"maxOpenConns": 100, // 最大连接数
"maxIdleConns": 10, // 最大空闲连接
"connMaxLifetime": 3600 // 连接最大生存时间（秒）
"maxOpenConns": 100, // 连接池配置
"maxIdleConns": 10,
"connMaxLifetime": 3600
},
"rateLimit": {
"enable": true, // 开启限流
"rate": 100,
"period": 60,
"byIP": true
}
}
```
### 使用建议
- ✅ 使用工厂黑盒模式，减少重复代码
- ✅ 生产环境开启异步日志和限流
- ✅ 配置Recovery中间件防止panic
- ✅ 明确指定CORS允许的源
- ❌ 避免在循环中创建logger
- ❌ 避免使用同步日志记录大量日志
## 故障排除
### 问题1：循环导入错误
**错误**：`import cycle not allowed`
**解决**：使用 `middleware.NewCORSConfig()` 转换配置
```go
configCORS := cfg.GetCORS()
middlewareCORS := middleware.NewCORSConfig(
configCORS.AllowedOrigins,
configCORS.AllowedMethods,
configCORS.AllowedHeaders,
configCORS.ExposedHeaders,
configCORS.AllowCredentials,
configCORS.MaxAge,
)
```
### 问题2：IDE显示导入错误
**错误**：`could not import git.toowon.com/jimmy/go-common/logger`
**解决**：重置Go模块缓存
```bash
go clean -modcache
go mod download
# 重启IDE的Language Server
```
### 问题3：限流不生效
**原因**：分布式部署下，内存存储只在单机生效
**解决**：分布式场景建议使用Redis实现限流
更多问题请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
常见问题请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
## 贡献指南