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 af3da72fd3
15 changed files with 635 additions and 1039 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
QUICKSTART.md
View File

@@ -34,6 +34,12 @@ go get git.toowon.com/jimmy/go-common@latest
"level": "info",
"output": "stdout",
"async": true
},
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byIP": true
}
}
```
@@ -61,18 +67,12 @@ func main() {
panic(err)
}
// 获取logger
logger, _ := fac.GetLogger()
defer logger.Close()
// 使用factory的黑盒方法获取中间件链
// 自动从配置文件读取并配置所有中间件
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, yourMetricsMiddleware)
// 注册路由
http.Handle("/api/hello", chain.ThenFunc(handleHello))
@@ -284,21 +284,57 @@ loggerConfig := &config.LoggerConfig{
}
```
### Q: 如何按用户ID限流？
### Q: 如何添加自定义中间件？
```go
limiter := middleware.NewTokenBucketLimiter(100, time.Minute)
rateLimitConfig := &middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: func(r *http.Request) string {
return r.Header.Get("X-User-ID")
},
}
chain := middleware.NewChain(
middleware.RateLimit(rateLimitConfig),
// 获取基础中间件链
chain := fac.GetMiddlewareChain()
// 添加自定义中间件
chain.Append(
yourAuthMiddleware, // 认证中间件
yourMetricsMiddleware, // 指标中间件
// 更多自定义中间件...
)
// 使用扩展后的中间件链
http.Handle("/api/secure", chain.ThenFunc(yourHandler))
```
自定义中间件示例：
```go
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "Unauthorized", 401)
return
}
// 验证token...
next.ServeHTTP(w, r)
})
}
```
### Q: 如何按用户ID限流？
在配置文件中设置：
```json
{
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byUserID": true,
"byIP": false
}
}
```
中间件会自动从 `X-User-ID` header 中获取用户ID进行限流。
## 下一步
恭喜！你已经掌握了 GoCommon 的基本使用。

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)
## 贡献指南

32
config/config.go
View File

@@ -17,6 +17,7 @@ type Config struct {
Email *EmailConfig `json:"email"`
SMS *SMSConfig `json:"sms"`
Logger *LoggerConfig `json:"logger"`
RateLimit *RateLimitConfig `json:"rateLimit"`
}
// DatabaseConfig 数据库配置
@@ -244,6 +245,24 @@ type LoggerConfig struct {
BufferSize int `json:"bufferSize"`
}
// RateLimitConfig 限流配置
type RateLimitConfig struct {
// Enable 是否启用限流
Enable bool `json:"enable"`
// Rate 每个时间窗口允许的请求数量
Rate int `json:"rate"`
// Period 时间窗口（秒）
Period int `json:"period"`
// ByIP 按IP限流
ByIP bool `json:"byIP"`
// ByUserID 按用户ID限流（从X-User-ID header获取）
ByUserID bool `json:"byUserID"`
}
// LoadFromFile 从文件加载配置
// filePath: 配置文件路径（支持绝对路径和相对路径）
func LoadFromFile(filePath string) (*Config, error) {
@@ -378,6 +397,19 @@ func (c *Config) setDefaults() {
c.Logger.Output = "stdout"
}
}
// 限流默认值
if c.RateLimit != nil {
if c.RateLimit.Rate == 0 {
c.RateLimit.Rate = 100 // 默认每个窗口100个请求
}
if c.RateLimit.Period == 0 {
c.RateLimit.Period = 60 // 默认时间窗口60秒
}
if !c.RateLimit.ByIP && !c.RateLimit.ByUserID {
c.RateLimit.ByIP = true // 默认按IP限流
}
}
}
// GetDatabase 获取数据库配置

7
config/example.json
View File

@@ -78,6 +78,13 @@
"disableTimestamp": false,
"async": false,
"bufferSize": 1000
},
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byIP": true,
"byUserID": false
}
}

25
docs/factory.md
View File

@@ -12,6 +12,31 @@
- **统一接口**：所有操作通过工厂方法调用
- **向后兼容**：保留 `GetXXX()` 方法，需要时可获取对象
## 方法分类总览
### 🌟 推荐使用：黑盒方法（一行代码搞定）
外部项目直接调用，无需获取内部对象：
| 功能 | 方法 | 示例 |
|------|------|------|
| **中间件** | `GetMiddlewareChain()` | `chain := fac.GetMiddlewareChain()` |
| **日志** | `LogInfo()`, `LogError()` 等 | `fac.LogInfo("用户登录")` |
| **Redis** | `RedisSet()`, `RedisGet()` 等 | `fac.RedisSet(ctx, "key", "val", time.Hour)` |
| **邮件** | `SendEmail()` | `fac.SendEmail(to, subject, body)` |
| **短信** | `SendSMS()` | `fac.SendSMS(phones, params)` |
| **存储** | `UploadFile()`, `GetFileURL()` | `fac.UploadFile(ctx, key, file)` |
### 🔧 高级功能：Get方法（仅在必要时使用）
返回客户端对象，用于复杂操作：
| 方法 | 返回类型 | 使用场景 |
|------|----------|----------|
| `GetDatabase()` | `*gorm.DB` | 数据库复杂查询、事务、关联查询等 |
| `GetRedisClient()` | `*redis.Client` | Hash、List、Set、ZSet、Pub/Sub等高级操作 |
| `GetLogger()` | `*logger.Logger` | Close()、设置全局logger等 |
## 使用方法
### 1. 创建工厂（推荐）

172
examples/factory_blackbox_example.go Normal file
View File

@@ -0,0 +1,172 @@
package main
import (
"context"
"log"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 示例：Factory黑盒模式 - 最简化的使用方式
//
// 核心理念：
//
// 外部项目只需要传递一个配置文件路径，
// 直接使用 factory 的黑盒方法，无需获取内部对象
func main() {
// ====== 第1步：创建工厂（只需要配置文件路径）======
fac, err := factory.NewFactoryFromFile("config.json")
if err != nil {
log.Fatal(err)
}
// ====== 第2步：使用黑盒方法（推荐）======
// 1. 获取中间件链（自动配置所有基础中间件）
chain := fac.GetMiddlewareChain()
// 2. 添加项目特定的自定义中间件
chain.Append(authMiddleware, metricsMiddleware)
// 3. 注册路由
http.Handle("/api/users", chain.ThenFunc(handleUsers))
http.Handle("/api/upload", chain.ThenFunc(handleUpload))
// 4. 启动服务
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
// ====== API处理器 ======
// 用户列表
func handleUsers(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 创建工厂（在处理器中也可以复用）
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 1. 使用数据库（需要获取对象，因为GORM很复杂）
db, _ := fac.GetDatabase()
var users []map[string]interface{}
db.Table("users").Find(&users)
// 2. 使用Redis（黑盒方法，推荐）
cacheKey := "users:list"
cached, _ := fac.RedisGet(ctx, cacheKey)
if cached != "" {
h.Success(cached)
return
}
// 3. 记录日志（黑盒方法，推荐）
fac.LogInfof(map[string]interface{}{
"action": "list_users",
"count": len(users),
}, "查询用户列表")
// 4. 缓存结果
fac.RedisSet(ctx, cacheKey, users, 5*time.Minute)
h.Success(users)
}
// 文件上传
func handleUpload(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 解析上传的文件
file, header, err := r.FormFile("file")
if err != nil {
fac.LogError("文件上传失败: %v", err)
h.Error(400, "文件上传失败")
return
}
defer file.Close()
// 上传文件（黑盒方法，自动选择OSS或MinIO）
objectKey := "uploads/" + header.Filename
url, err := fac.UploadFile(ctx, objectKey, file, header.Header.Get("Content-Type"))
if err != nil {
fac.LogError("文件上传到存储失败: %v", err)
h.Error(500, "文件上传失败")
return
}
// 记录上传日志
fac.LogInfof(map[string]interface{}{
"filename": header.Filename,
"size": header.Size,
"url": url,
}, "文件上传成功")
h.Success(map[string]interface{}{
"url": url,
})
}
// ====== 自定义中间件 ======
// 认证中间件
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 获取token
token := r.Header.Get("Authorization")
if token == "" {
h := commonhttp.NewHandler(w, r)
h.Error(401, "未授权")
return
}
// 从Redis验证token（黑盒方法）
userID, err := fac.RedisGet(ctx, "token:"+token)
if err != nil || userID == "" {
h := commonhttp.NewHandler(w, r)
h.Error(401, "token无效")
return
}
// 记录日志（黑盒方法）
fac.LogInfof(map[string]interface{}{
"user_id": userID,
"path": r.URL.Path,
}, "用户请求")
// 将用户ID存入context（或header）
r.Header.Set("X-User-ID", userID)
next.ServeHTTP(w, r)
})
}
// 指标中间件
func metricsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
start := time.Now()
// 继续处理请求
next.ServeHTTP(w, r)
// 记录请求耗时到Redis（黑盒方法）
latency := time.Since(start).Milliseconds()
key := "metrics:" + r.URL.Path
fac.RedisSet(ctx, key, latency, time.Minute)
// 记录指标日志（黑盒方法）
fac.LogDebugf(map[string]interface{}{
"path": r.URL.Path,
"latency": latency,
}, "请求指标")
})
}

186
examples/factory_example.go
View File

@@ -1,186 +0,0 @@
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"git.toowon.com/jimmy/go-common/factory"
"github.com/redis/go-redis/v9"
)
func main() {
// 方式1：直接从配置文件创建工厂（推荐）
fac, err := factory.NewFactoryFromFile("./config/example.json")
if err != nil {
log.Fatal("Failed to create factory:", err)
}
ctx := context.Background()
// ========== 日志记录（黑盒模式，推荐） ==========
fac.LogInfo("应用启动")
fac.LogDebug("调试信息: %s", "test")
fac.LogWarn("警告信息")
fac.LogError("错误信息: %v", fmt.Errorf("test error"))
// 带字段的日志
fac.LogInfof(map[string]interface{}{
"user_id": 123,
"ip": "192.168.1.1",
}, "用户登录成功")
fac.LogErrorf(map[string]interface{}{
"error_code": 1001,
"user_id": 123,
}, "登录失败: %v", fmt.Errorf("invalid password"))
// ========== 邮件发送（黑盒模式，推荐） ==========
err = fac.SendEmail(
[]string{"user@example.com"},
"验证码",
"您的验证码是：123456",
)
if err != nil {
fac.LogError("发送邮件失败: %v", err)
} else {
fac.LogInfo("邮件发送成功")
}
// HTML邮件
err = fac.SendEmail(
[]string{"user@example.com"},
"欢迎",
"纯文本内容",
"<h1>HTML内容</h1>",
)
if err != nil {
fac.LogError("发送HTML邮件失败: %v", err)
}
// ========== 短信发送（黑盒模式，推荐） ==========
resp, err := fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
)
if err != nil {
fac.LogError("发送短信失败: %v", err)
} else {
fac.LogInfo("短信发送成功: %s", resp.RequestID)
}
// 指定模板代码
resp, err = fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
"SMS_123456789", // 模板代码
)
if err != nil {
fac.LogError("发送短信失败: %v", err)
}
// ========== 文件上传（黑盒模式，推荐，自动选择OSS或MinIO） ==========
file, err := os.Open("test.jpg")
if err == nil {
defer file.Close()
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
if err != nil {
fac.LogError("上传文件失败: %v", err)
} else {
fac.LogInfo("文件上传成功: %s", url)
}
}
// ========== 获取文件URL（黑盒模式） ==========
// 永久有效
url, err := fac.GetFileURL("images/test.jpg", 0)
if err != nil {
fac.LogError("获取文件URL失败: %v", err)
} else {
fac.LogInfo("文件URL: %s", url)
}
// 临时访问URL（1小时后过期）
url, err = fac.GetFileURL("images/test.jpg", 3600)
if err != nil {
fac.LogError("获取临时URL失败: %v", err)
} else {
fac.LogInfo("临时URL: %s", url)
}
// ========== Redis操作（黑盒模式，推荐） ==========
// 设置值（不过期）
err = fac.RedisSet(ctx, "user:123", "value")
if err != nil {
fac.LogError("Redis设置失败: %v", err)
}
// 设置值（带过期时间）
err = fac.RedisSet(ctx, "user:123", "value", time.Hour)
if err != nil {
fac.LogError("Redis设置失败: %v", err)
}
// 获取值
value, err := fac.RedisGet(ctx, "user:123")
if err != nil {
fac.LogError("Redis获取失败: %v", err)
} else {
fac.LogInfo("Redis值: %s", value)
}
// 删除键
err = fac.RedisDelete(ctx, "user:123", "user:456")
if err != nil {
fac.LogError("Redis删除失败: %v", err)
}
// 检查键是否存在
exists, err := fac.RedisExists(ctx, "user:123")
if err != nil {
fac.LogError("Redis检查失败: %v", err)
} else {
fac.LogInfo("键是否存在: %v", exists)
}
// ========== 数据库操作（黑盒模式，获取对象） ==========
db, err := fac.GetDatabase()
if err != nil {
fac.LogError("数据库连接失败: %v", err)
} else {
// 直接使用GORM，无需自己实现创建逻辑
var count int64
if err := db.Table("users").Count(&count).Error; err != nil {
fac.LogError("查询用户数量失败: %v", err)
} else {
fac.LogInfo("用户数量: %d", count)
}
}
// ========== Redis操作（获取客户端对象，黑盒模式） ==========
redisClient, err := fac.GetRedisClient()
if err != nil {
fac.LogError("Redis客户端不可用: %v", err)
} else {
// 直接使用Redis客户端，无需自己实现创建逻辑
val, err := redisClient.Get(ctx, "test_key").Result()
if err != nil && err != redis.Nil {
fac.LogError("Redis错误: %v", err)
} else if err == redis.Nil {
fac.LogInfo("Redis键不存在")
} else {
fac.LogInfo("Redis值: %s", val)
}
// 使用高级功能（如Hash操作）
redisClient.HSet(ctx, "user:123", "name", "John")
name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
fac.LogInfo("Redis Hash值: %s", name)
}
fac.LogInfo("示例执行完成")
}

154
examples/middleware_full_example.go
View File

@@ -1,154 +0,0 @@
package main
import (
"log"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/config"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/logger"
"git.toowon.com/jimmy/go-common/middleware"
)
// 示例：完整的中间件配置
// 包括：Recovery、Logging、RateLimit、CORS、Timezone
func main() {
// 1. 配置logger（异步模式，输出到文件和stdout）
loggerConfig := &logger.LoggerConfig{
Level: "info",
Output: "both", // 同时输出到stdout和文件
FilePath: "./logs/app.log",
Async: true, // 异步模式
BufferSize: 1000, // 缓冲区大小
Prefix: "[API]", // 日志前缀
}
myLogger, err := logger.NewLogger(loggerConfig)
if err != nil {
log.Fatal("Failed to create logger:", err)
}
defer myLogger.Close() // 确保程序退出时关闭logger
// 2. 配置CORS
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Timezone"},
ExposedHeaders: []string{"X-Total-Count"},
AllowCredentials: false,
MaxAge: 3600, // 1小时
}
// 3. 配置日志中间件
loggingConfig := &middleware.LoggingConfig{
Logger: myLogger,
SkipPaths: []string{"/health", "/metrics"}, // 跳过健康检查和监控接口
}
// 4. 配置Recovery中间件
recoveryConfig := &middleware.RecoveryConfig{
Logger: myLogger,
EnableStackTrace: true, // 启用堆栈跟踪
CustomHandler: func(w http.ResponseWriter, r *http.Request, err interface{}) {
// 使用统一的JSON响应格式
h := commonhttp.NewHandler(w, r)
h.SystemError("服务器内部错误，请稍后重试")
},
}
// 5. 配置限流中间件（100请求/分钟）
rateLimiter := middleware.NewTokenBucketLimiter(100, time.Minute)
rateLimitConfig := &middleware.RateLimitConfig{
Limiter: rateLimiter,
OnRateLimitExceeded: func(w http.ResponseWriter, r *http.Request, key string) {
// 记录限流事件
myLogger.Warnf(map[string]interface{}{
"key": key,
"path": r.URL.Path,
"ip": r.RemoteAddr,
}, "Rate limit exceeded")
},
}
// 6. 创建中间件链（顺序很重要！）
// 顺序：Recovery -> Logging -> RateLimit -> CORS -> Timezone
chain := middleware.NewChain(
middleware.Recovery(recoveryConfig), // 1. 最外层：捕获panic
middleware.Logging(loggingConfig), // 2. 日志记录
middleware.RateLimit(rateLimitConfig), // 3. 限流保护
middleware.CORS(corsConfig), // 4. CORS处理
middleware.Timezone, // 5. 时区处理
)
// 7. 定义路由
mux := http.NewServeMux()
// API路由（应用所有中间件）
mux.Handle("/api/hello", chain.ThenFunc(handleHello))
mux.Handle("/api/panic", chain.ThenFunc(handlePanic)) // 测试panic恢复
mux.Handle("/api/users", chain.ThenFunc(handleUsers))
// 健康检查（不应用中间件链，直接处理）
mux.HandleFunc("/health", handleHealth)
mux.HandleFunc("/metrics", handleMetrics)
// 8. 启动服务器
addr := ":8080"
log.Printf("Server starting on %s", addr)
log.Printf("Try: http://localhost%s/api/hello", addr)
log.Printf("Health: http://localhost%s/health", addr)
if err := http.ListenAndServe(addr, mux); err != nil {
log.Fatal("Server failed:", err)
}
}
// handleHello 示例处理器：返回问候信息
func handleHello(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 从Handler获取时区
timezone := h.GetTimezone()
h.Success(map[string]interface{}{
"message": "Hello, World!",
"timezone": timezone,
"method": r.Method,
"path": r.URL.Path,
})
}
// handlePanic 示例处理器：测试panic恢复
func handlePanic(w http.ResponseWriter, r *http.Request) {
// 故意触发panic，测试Recovery中间件
panic("This is a test panic!")
}
// handleUsers 示例处理器：返回用户列表
func handleUsers(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 模拟用户数据
users := []map[string]interface{}{
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
{"id": 3, "name": "Charlie"},
}
h.Success(users)
}
// handleHealth 健康检查处理器（不应用中间件）
func handleHealth(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain")
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
}
// handleMetrics 监控指标处理器（不应用中间件）
func handleMetrics(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain")
w.WriteHeader(http.StatusOK)
w.Write([]byte("metrics: ok"))
}

89
examples/middleware_ratelimit_example.go
View File

@@ -1,89 +0,0 @@
package main
import (
"log"
"net/http"
"time"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/middleware"
)
// 示例：限流中间件的使用
// 展示不同的限流策略
func main() {
// 策略1：按IP限流（10请求/分钟）
ipLimitChain := middleware.NewChain(
middleware.RateLimitByIP(10, time.Minute),
)
// 策略2：按用户ID限流（100请求/分钟）
limiter := middleware.NewTokenBucketLimiter(100, time.Minute)
userLimitConfig := &middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: func(r *http.Request) string {
// 从请求头获取用户ID
userID := r.Header.Get("X-User-ID")
if userID != "" {
return "user:" + userID
}
// 没有用户ID则使用IP
return "ip:" + r.RemoteAddr
},
OnRateLimitExceeded: func(w http.ResponseWriter, r *http.Request, key string) {
log.Printf("Rate limit exceeded for key: %s, path: %s", key, r.URL.Path)
},
}
userLimitChain := middleware.NewChain(
middleware.RateLimit(userLimitConfig),
)
// 路由1：按IP限流的API（严格限制）
http.Handle("/api/public", ipLimitChain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
h.Success(map[string]interface{}{
"message": "Public API - IP rate limited (10/min)",
"tip": "Try refreshing quickly to see rate limiting",
})
}))
// 路由2：按用户ID限流的API（宽松限制）
http.Handle("/api/private", userLimitChain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
userID := r.Header.Get("X-User-ID")
if userID == "" {
h.Error(401, "Missing X-User-ID header")
return
}
h.Success(map[string]interface{}{
"message": "Private API - User rate limited (100/min)",
"user_id": userID,
})
}))
// 路由3：无限流的API（用于测试对比）
http.HandleFunc("/api/unlimited", func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
h.Success(map[string]interface{}{
"message": "Unlimited API - No rate limiting",
})
})
// 启动服务器
addr := ":8080"
log.Printf("Server starting on %s", addr)
log.Println("Test endpoints:")
log.Printf(" - IP limited (10/min): http://localhost%s/api/public", addr)
log.Printf(" - User limited (100/min): http://localhost%s/api/private (add X-User-ID header)", addr)
log.Printf(" - No limit: http://localhost%s/api/unlimited", addr)
log.Println("\nTest with curl:")
log.Printf(" curl http://localhost%s/api/public", addr)
log.Printf(" curl -H 'X-User-ID: user123' http://localhost%s/api/private", addr)
log.Println("\nResponse headers:")
log.Println(" X-RateLimit-Limit: Total allowed requests")
log.Println(" X-RateLimit-Remaining: Remaining requests")
log.Println(" X-RateLimit-Reset: Reset timestamp")
log.Fatal(http.ListenAndServe(addr, nil))
}

58
examples/migration_example.go
View File

@@ -1,58 +0,0 @@
package main
import (
"fmt"
"log"
"gorm.io/driver/mysql"
"gorm.io/gorm"
"git.toowon.com/jimmy/go-common/migration"
)
func main() {
// 初始化数据库连接
dsn := "user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
log.Fatal(err)
}
// 创建迁移器
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 IF NOT EXISTS users (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
`).Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE IF EXISTS users").Error
},
})
// 执行迁移
if err := migrator.Up(); err != nil {
log.Fatal(err)
}
// 查看迁移状态
status, err := migrator.Status()
if err != nil {
log.Fatal(err)
}
for _, s := range status {
fmt.Printf("Version: %s, Description: %s, Applied: %v\n",
s.Version, s.Description, s.Applied)
}
}

105
examples/migration_reset_example.go
View File

@@ -1,105 +0,0 @@
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/migration"
"gorm.io/driver/sqlite"
"gorm.io/gorm"
)
func main() {
// 初始化数据库连接（使用SQLite作为示例）
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
if err != nil {
log.Fatal("Failed to connect to database:", err)
}
// 创建迁移器
migrator := migration.NewMigrator(db)
// 添加一些迁移
migrator.AddMigrations(
migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec(`
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
)
`).Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE IF EXISTS users").Error
},
},
migration.Migration{
Version: "20240101000002",
Description: "add_created_at_to_users",
Up: func(db *gorm.DB) error {
return db.Exec("ALTER TABLE users ADD COLUMN created_at DATETIME").Error
},
Down: func(db *gorm.DB) error {
return db.Exec("ALTER TABLE users DROP COLUMN created_at").Error
},
},
)
// 执行迁移
fmt.Println("=== Executing migrations ===")
err = migrator.Up()
if err != nil {
log.Fatal("Failed to run migrations:", err)
}
// 查看状态
fmt.Println("\n=== Migration status ===")
status, err := migrator.Status()
if err != nil {
log.Fatal("Failed to get status:", err)
}
for _, s := range status {
fmt.Printf("Version: %s, Description: %s, Applied: %v\n",
s.Version, s.Description, s.Applied)
}
// 示例1：仅清空迁移记录（不回滚数据库变更）
fmt.Println("\n=== Example 1: Reset migration records only ===")
fmt.Println("Note: This only clears records, not database changes")
// 直接调用（需要确认标志）
// err = migrator.Reset(true)
// if err != nil {
// log.Fatal("Failed to reset:", err)
// }
// 交互式确认（推荐）
// 取消注释下面的代码来测试交互式重置
// err = migrator.ResetWithConfirm()
// if err != nil {
// log.Fatal("Failed to reset with confirm:", err)
// }
// 示例2：回滚所有迁移并清空记录
fmt.Println("\n=== Example 2: Reset all migrations (rollback + clear records) ===")
fmt.Println("Note: This will rollback all migrations and clear records")
// 直接调用（需要确认标志）
// err = migrator.ResetAll(true)
// if err != nil {
// log.Fatal("Failed to reset all:", err)
// }
// 交互式确认（推荐）
// 取消注释下面的代码来测试交互式重置
// err = migrator.ResetAllWithConfirm()
// if err != nil {
// log.Fatal("Failed to reset all with confirm:", err)
// }
fmt.Println("\nNote: Reset functions are commented out for safety.")
fmt.Println("Uncomment the code above to test reset functionality.")
}

224
factory/factory.go
View File

@@ -4,11 +4,13 @@ import (
"context"
"fmt"
"io"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
"git.toowon.com/jimmy/go-common/logger"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/sms"
"git.toowon.com/jimmy/go-common/storage"
"github.com/redis/go-redis/v9"
@@ -18,6 +20,41 @@ import (
"gorm.io/gorm"
)
// Factory 工厂类 - 黑盒模式设计
//
// 核心理念：
//
// 外部项目只需传递一个配置文件路径，即可直接使用所有功能，
// 无需关心内部实现细节。
//
// 推荐使用的黑盒方法：
// - GetMiddlewareChain()：获取配置好的中间件链
// - LogInfo(), LogError()：记录日志
// - RedisSet(), RedisGet()：操作Redis
// - SendEmail(), SendSMS()：发送邮件和短信
// - UploadFile(), GetFileURL()：文件上传和访问
//
// 需要获取客户端对象的场景（高级功能）：
// - GetDatabase()：数据库操作（GORM已经是很好的抽象）
// - GetRedisClient()：Redis高级操作（Hash, List, Set, ZSet等）
// - GetLogger()：Logger高级功能（Close等）
//
// 使用示例：
//
// // 1. 创建工厂（传入配置文件路径）
// fac, _ := factory.NewFactoryFromFile("config.json")
//
// // 2. 直接使用黑盒方法（推荐）
// fac.LogInfo("用户登录成功")
// fac.RedisSet(ctx, "session:123", "data", time.Hour)
// fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
// chain := fac.GetMiddlewareChain()
// chain.Append(yourAuthMiddleware) // 添加自定义中间件
//
// // 3. 获取客户端对象（仅在需要高级功能时）
// db, _ := fac.GetDatabase()
// db.Find(&users)
//
// Factory 工厂类，用于从配置创建各种客户端对象
type Factory struct {
cfg *config.Config
@@ -65,7 +102,8 @@ func (f *Factory) getEmailClient() (*email.Email, error) {
return e, nil
}
// SendEmail 发送邮件（黑盒模式）
// SendEmail 发送邮件（黑盒模式，推荐使用）
// 自动使用配置文件中的SMTP配置发送邮件
// to: 收件人列表
// subject: 邮件主题
// body: 邮件正文（纯文本）
@@ -108,7 +146,8 @@ func (f *Factory) getSMSClient() (*sms.SMS, error) {
return s, nil
}
// SendSMS 发送短信（黑盒模式）
// SendSMS 发送短信（黑盒模式，推荐使用）
// 自动使用配置文件中的阿里云短信配置发送短信
// phoneNumbers: 手机号列表
// templateParam: 模板参数（map或JSON字符串）
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
@@ -153,15 +192,31 @@ func (f *Factory) getLogger() (*logger.Logger, error) {
return l, nil
}
// GetLogger 获取日志记录器对象（已初始化）
// 返回已初始化的日志记录器对象，可直接使用
// 注意：推荐使用 LogDebug、LogInfo、LogWarn、LogError 等方法直接记录日志
// 如果需要使用logger的高级功能（如Close方法），可以使用此方法获取logger对象
// GetLogger 获取日志记录器对象（不推荐直接使用）
//
// ⚠️ 不推荐直接使用此方法，推荐使用黑盒方法：
// - LogDebug, LogInfo, LogWarn, LogError（记录简单日志）
// - LogDebugf, LogInfof, LogWarnf, LogErrorf（记录带字段的日志）
//
// 仅在以下高级场景时使用：
// - 需要调用 Close() 方法关闭logger
// - 需要使用logger的其他高级功能
//
// 示例（不推荐）：
//
// logger, _ := factory.GetLogger()
// defer logger.Close()
//
// 示例（推荐）：
//
// factory.LogInfo("用户登录成功")
// factory.LogErrorf(map[string]interface{}{"user_id": 123}, "登录失败")
func (f *Factory) GetLogger() (*logger.Logger, error) {
return f.getLogger()
}
// LogDebug 记录调试日志
// LogDebug 记录调试日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogDebug(message string, args ...interface{}) {
@@ -182,7 +237,8 @@ func (f *Factory) LogDebug(message string, args ...interface{}) {
}
}
// LogDebugf 记录调试日志（带字段）
// LogDebugf 记录调试日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -200,7 +256,8 @@ func (f *Factory) LogDebugf(fields map[string]interface{}, message string, args
l.Debugf(fields, message, args...)
}
// LogInfo 记录信息日志
// LogInfo 记录信息日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogInfo(message string, args ...interface{}) {
@@ -221,7 +278,8 @@ func (f *Factory) LogInfo(message string, args ...interface{}) {
}
}
// LogInfof 记录信息日志（带字段）
// LogInfof 记录信息日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -239,7 +297,8 @@ func (f *Factory) LogInfof(fields map[string]interface{}, message string, args .
l.Infof(fields, message, args...)
}
// LogWarn 记录警告日志
// LogWarn 记录警告日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogWarn(message string, args ...interface{}) {
@@ -260,7 +319,8 @@ func (f *Factory) LogWarn(message string, args ...interface{}) {
}
}
// LogWarnf 记录警告日志（带字段）
// LogWarnf 记录警告日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -278,7 +338,8 @@ func (f *Factory) LogWarnf(fields map[string]interface{}, message string, args .
l.Warnf(fields, message, args...)
}
// LogError 记录错误日志
// LogError 记录错误日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogError(message string, args ...interface{}) {
@@ -299,7 +360,8 @@ func (f *Factory) LogError(message string, args ...interface{}) {
}
}
// LogErrorf 记录错误日志（带字段）
// LogErrorf 记录错误日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -370,9 +432,20 @@ func (f *Factory) getDatabase() (*gorm.DB, error) {
return db, nil
}
// GetDatabase 获取数据库连接对象（已初始化）
// GetDatabase 获取数据库连接对象（推荐使用）
// 返回已初始化的GORM数据库对象，可直接使用
// 注意：数据库保持返回GORM对象，因为GORM已经提供了很好的抽象
//
// ℹ️ 数据库操作保持使用 GORM 对象，因为：
// - 数据库操作非常复杂多样（查询、插入、更新、删除、事务等）
// - GORM 已经提供了很好的抽象和 API
// - 无需在 factory 中重复封装所有数据库方法
//
// 示例：
//
// db, _ := factory.GetDatabase()
// db.Find(&users)
// db.Create(&user)
// db.Transaction(func(tx *gorm.DB) error { ... })
func (f *Factory) GetDatabase() (*gorm.DB, error) {
return f.getDatabase()
}
@@ -438,15 +511,35 @@ func (f *Factory) getRedisClient() (*redis.Client, error) {
return client, nil
}
// GetRedisClient 获取Redis客户端对象（已初始化）
// 返回已初始化的Redis客户端对象，可直接使用
// 注意：推荐使用 RedisGet、RedisSet、RedisDelete 等方法直接操作Redis
// 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
// GetRedisClient 获取Redis客户端对象（高级功能时使用）
// 返回已初始化的Redis客户端对象
//
// ℹ️ 推荐使用黑盒方法：
// - RedisGet, RedisSet, RedisDelete, RedisExists（常用操作）
//
// 仅在需要使用高级功能时获取客户端：
// - Hash 操作（HSet, HGet, HGetAll 等）
// - List 操作（LPush, RPush, LRange 等）
// - Set 操作（SAdd, SMembers 等）
// - ZSet 操作（ZAdd, ZRange 等）
// - 其他高级功能
//
// 示例（常用操作，推荐）：
//
// factory.RedisSet(ctx, "key", "value", time.Hour)
// value, _ := factory.RedisGet(ctx, "key")
//
// 示例（高级功能）：
//
// client, _ := factory.GetRedisClient()
// client.HSet(ctx, "user:1", "name", "Alice")
// client.LPush(ctx, "queue", "task1")
func (f *Factory) GetRedisClient() (*redis.Client, error) {
return f.getRedisClient()
}
// RedisGet 获取Redis值（黑盒模式）
// RedisGet 获取Redis值（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {
client, err := f.getRedisClient()
@@ -465,7 +558,8 @@ func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {
return result, nil
}
// RedisSet 设置Redis值（黑盒模式）
// RedisSet 设置Redis值（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
// value: Redis值
// expiration: 过期时间（可选，0表示不过期）
@@ -488,7 +582,8 @@ func (f *Factory) RedisSet(ctx context.Context, key string, value interface{}, e
return nil
}
// RedisDelete 删除Redis键（黑盒模式）
// RedisDelete 删除Redis键（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// keys: Redis键列表
func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
if len(keys) == 0 {
@@ -508,7 +603,8 @@ func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
return nil
}
// RedisExists 检查Redis键是否存在（黑盒模式）
// RedisExists 检查Redis键是否存在（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
func (f *Factory) RedisExists(ctx context.Context, key string) (bool, error) {
client, err := f.getRedisClient()
@@ -556,7 +652,8 @@ func (f *Factory) getStorage() (storage.Storage, error) {
return s, nil
}
// UploadFile 上传文件
// UploadFile 上传文件（黑盒模式，推荐使用）
// 自动根据配置选择存储类型（OSS 或 MinIO），无需关心内部实现
// ctx: 上下文
// objectKey: 对象键（文件路径）
// reader: 文件内容
@@ -583,8 +680,9 @@ func (f *Factory) UploadFile(ctx context.Context, objectKey string, reader io.Re
return url, nil
}
// GetFileURL 获取文件访问URL（Show方法）
// objectKey: 对象键
// GetFileURL 获取文件访问URL（黑盒模式，推荐使用）
// 自动根据配置选择存储类型，返回文件的访问URL
// objectKey: 对象键（文件路径）
// expires: 过期时间（秒），0表示永久有效
func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
s, err := f.getStorage()
@@ -594,3 +692,75 @@ func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
return s.GetURL(objectKey, expires)
}
// GetMiddlewareChain 获取配置好的中间件链（黑盒模式）
// 自动包含：Recovery、Logging、RateLimit（如果配置了）、CORS（如果配置了）、Timezone
// 返回已配置好的中间件链，可以通过 Append() 方法添加自定义中间件
//
// 示例1：直接使用
//
// chain := factory.GetMiddlewareChain()
// http.Handle("/api/users", chain.ThenFunc(handleUsers))
//
// 示例2：添加自定义中间件
//
// chain := factory.GetMiddlewareChain()
// chain.Append(yourCustomMiddleware1, yourCustomMiddleware2)
// http.Handle("/api/users", chain.ThenFunc(handleUsers))
func (f *Factory) GetMiddlewareChain() *middleware.Chain {
var middlewares []func(http.Handler) http.Handler
// 1. Recovery 中间件（必需，防止panic导致服务崩溃）
l, _ := f.getLogger() // 获取logger，如果失败会使用默认logger
middlewares = append(middlewares, middleware.Recovery(&middleware.RecoveryConfig{
Logger: l,
}))
// 2. Logging 中间件（必需，记录所有请求）
middlewares = append(middlewares, middleware.Logging(&middleware.LoggingConfig{
Logger: l,
}))
// 3. RateLimit 中间件（如果配置了限流）
if f.cfg != nil && f.cfg.RateLimit != nil {
if f.cfg.RateLimit.Enable {
// 从配置创建限流中间件
limiter := middleware.NewTokenBucketLimiter(
f.cfg.RateLimit.Rate,
time.Duration(f.cfg.RateLimit.Period)*time.Second,
)
var keyFunc func(r *http.Request) string
if f.cfg.RateLimit.ByIP {
keyFunc = func(r *http.Request) string {
return middleware.GetClientIP(r)
}
} else if f.cfg.RateLimit.ByUserID {
keyFunc = func(r *http.Request) string {
return r.Header.Get("X-User-ID")
}
}
middlewares = append(middlewares, middleware.RateLimit(&middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: keyFunc,
}))
}
}
// 4. CORS 中间件（如果配置了）
if f.cfg != nil && f.cfg.CORS != nil {
corsConfig := &middleware.CORSConfig{
AllowedOrigins: f.cfg.CORS.AllowedOrigins,
AllowedMethods: f.cfg.CORS.AllowedMethods,
AllowedHeaders: f.cfg.CORS.AllowedHeaders,
ExposedHeaders: f.cfg.CORS.ExposedHeaders,
AllowCredentials: f.cfg.CORS.AllowCredentials,
MaxAge: f.cfg.CORS.MaxAge,
}
middlewares = append(middlewares, middleware.CORS(corsConfig))
}
// 5. Timezone 中间件（必需，处理时区）
middlewares = append(middlewares, middleware.Timezone)
return middleware.NewChain(middlewares...)
}

6
middleware/logging.go
View File

@@ -123,7 +123,7 @@ func shouldSkipPath(path string, skipPaths []string) bool {
// logHTTPRequest 记录HTTP请求日志
func logHTTPRequest(log *logger.Logger, r *http.Request, rw *responseWriter, duration time.Duration) {
// 获取客户端IP
clientIP := getClientIP(r)
clientIP := GetClientIP(r)
// 构建日志字段
fields := map[string]interface{}{
@@ -188,9 +188,9 @@ func formatValue(v interface{}) string {
}
}
// getClientIP 获取客户端真实IP
// GetClientIP 获取客户端真实IP
// 优先级：X-Forwarded-For > X-Real-IP > RemoteAddr
func getClientIP(r *http.Request) string {
func GetClientIP(r *http.Request) string {
// 尝试从 X-Forwarded-For 获取
xff := r.Header.Get("X-Forwarded-For")
if xff != "" {

4
middleware/ratelimit.go
View File

@@ -169,7 +169,7 @@ func RateLimit(config *RateLimitConfig) func(http.Handler) http.Handler {
// 如果没有提供KeyFunc，使用默认的（客户端IP）
if config.KeyFunc == nil {
config.KeyFunc = func(r *http.Request) string {
return getClientIP(r)
return GetClientIP(r)
}
}
@@ -223,7 +223,7 @@ func RateLimitByIP(rate int, windowSize time.Duration) func(http.Handler) http.H
return RateLimit(&RateLimitConfig{
Limiter: NewTokenBucketLimiter(rate, windowSize),
KeyFunc: func(r *http.Request) string {
return getClientIP(r)
return GetClientIP(r)
},
})
}

2
middleware/recovery.go
View File

@@ -109,7 +109,7 @@ func logPanic(log *logger.Logger, r *http.Request, err interface{}, enableStackT
"method": r.Method,
"path": r.URL.Path,
"query": r.URL.RawQuery,
"ip": getClientIP(r),
"ip": GetClientIP(r),
"error": fmt.Sprintf("%v", err),
}