diff --git a/QUICKSTART.md b/QUICKSTART.md index c4d0b78..2b250f5 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -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 的基本使用。 diff --git a/README.md b/README.md index b5c4cf7..50f237f 100644 --- a/README.md +++ b/README.md @@ -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"}, "主题", "纯文本", "

HTML内容

") - -// 或获取客户端对象（需要高级功能时） -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) ## 贡献指南 diff --git a/config/config.go b/config/config.go index 4fda174..8ab4597 100644 --- a/config/config.go +++ b/config/config.go @@ -9,14 +9,15 @@ import ( // Config 应用配置 type Config struct { - Database *DatabaseConfig `json:"database"` - OSS *OSSConfig `json:"oss"` - Redis *RedisConfig `json:"redis"` - CORS *CORSConfig `json:"cors"` - MinIO *MinIOConfig `json:"minio"` - Email *EmailConfig `json:"email"` - SMS *SMSConfig `json:"sms"` - Logger *LoggerConfig `json:"logger"` + Database *DatabaseConfig `json:"database"` + OSS *OSSConfig `json:"oss"` + Redis *RedisConfig `json:"redis"` + CORS *CORSConfig `json:"cors"` + MinIO *MinIOConfig `json:"minio"` + 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 获取数据库配置 diff --git a/config/example.json b/config/example.json index d63a22f..a7af323 100644 --- a/config/example.json +++ b/config/example.json @@ -78,6 +78,13 @@ "disableTimestamp": false, "async": false, "bufferSize": 1000 + }, + "rateLimit": { + "enable": true, + "rate": 100, + "period": 60, + "byIP": true, + "byUserID": false } } diff --git a/docs/factory.md b/docs/factory.md index a407371..57fae8e 100644 --- a/docs/factory.md +++ b/docs/factory.md @@ -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. 创建工厂（推荐） diff --git a/examples/factory_blackbox_example.go b/examples/factory_blackbox_example.go new file mode 100644 index 0000000..b324d5e --- /dev/null +++ b/examples/factory_blackbox_example.go @@ -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, + }, "请求指标") + }) +} diff --git a/examples/factory_example.go b/examples/factory_example.go deleted file mode 100644 index edbafce..0000000 --- a/examples/factory_example.go +++ /dev/null @@ -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"}, - "欢迎", - "纯文本内容", - "

HTML内容

", - ) - 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("示例执行完成") -} diff --git a/examples/middleware_full_example.go b/examples/middleware_full_example.go deleted file mode 100644 index 46c4cf8..0000000 --- a/examples/middleware_full_example.go +++ /dev/null @@ -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")) -} - diff --git a/examples/middleware_ratelimit_example.go b/examples/middleware_ratelimit_example.go deleted file mode 100644 index 93663c4..0000000 --- a/examples/middleware_ratelimit_example.go +++ /dev/null @@ -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)) -} - diff --git a/examples/migration_example.go b/examples/migration_example.go deleted file mode 100644 index c9bfb0f..0000000 --- a/examples/migration_example.go +++ /dev/null @@ -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) - } -} - diff --git a/examples/migration_reset_example.go b/examples/migration_reset_example.go deleted file mode 100644 index ad211c9..0000000 --- a/examples/migration_reset_example.go +++ /dev/null @@ -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.") -} - diff --git a/factory/factory.go b/factory/factory.go index 5192bb6..65595fd 100644 --- a/factory/factory.go +++ b/factory/factory.go @@ -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...) +} diff --git a/middleware/logging.go b/middleware/logging.go index 5699287..da1e15d 100644 --- a/middleware/logging.go +++ b/middleware/logging.go @@ -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 != "" { diff --git a/middleware/ratelimit.go b/middleware/ratelimit.go index 5639b74..42a8101 100644 --- a/middleware/ratelimit.go +++ b/middleware/ratelimit.go @@ -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) }, }) } diff --git a/middleware/recovery.go b/middleware/recovery.go index c95c952..1ed966b 100644 --- a/middleware/recovery.go +++ b/middleware/recovery.go @@ -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), }