修复迁移时,数据库未指定的情况下数据库脚本混乱的问题

MIGRATION.md

@@ -105,14 +105,10 @@ go build -o bin/migrate cmd/migrate/main.go
 }
 ```
 
-#### 方式2：环境变量（推荐生产环境）
+#### 方式2：环境变量指定配置文件路径（推荐生产环境）
 
 ```bash
-# 使用 DATABASE_URL（最简单）
+# 使用环境变量指定配置文件路径
-export DATABASE_URL="mysql://root:password@localhost:3306/mydb"
-./bin/migrate up
-
-# 覆盖配置路径
 export CONFIG_FILE="/etc/app/config.json"
 export MIGRATIONS_DIR="/opt/app/migrations"
 ./bin/migrate up
@@ -122,8 +118,7 @@ export MIGRATIONS_DIR="/opt/app/migrations"
 
 1. 命令行参数 `-config` 和 `-dir`（最高）
 2. 环境变量 `CONFIG_FILE` 和 `MIGRATIONS_DIR`
-3. 环境变量 `DATABASE_URL`
+3. 默认值 `config.json` 和 `migrations`
-4. 默认值 `config.json` 和 `migrations`
 
 ---
 
@@ -185,20 +180,20 @@ services:
 docker-compose exec app ./migrate up
 ```
 
-### 方式3：使用环境变量
+### 方式3：使用环境变量指定配置文件路径
 
-无需配置文件（适用于简单场景）：
+适用于多环境部署，通过环境变量指定不同环境的配置文件：
 
 ```yaml
 services:
   app:
     build: .
     environment:
-      DATABASE_URL: mysql://root:password@db:3306/mydb
+      CONFIG_FILE: /app/config.prod.json
+      MIGRATIONS_DIR: /app/migrations
+    volumes:
+      - ./config.prod.json:/app/config.prod.json:ro
     command: sh -c "./migrate up && ./server"
-
-# 注意：DATABASE_URL 的值应该指向你的数据库服务
-# 例如：mysql://user:pass@your-db-host:3306/dbname
 ```
 
 ### Dockerfile
@@ -336,10 +331,12 @@ jobs:
           go build -o bin/migrate cmd/migrate/main.go
           go build -o bin/server cmd/server/main.go
       
+      - name: Create Config File
+        run: |
+          echo '${{ secrets.CONFIG_JSON }}' > config.json
+      
       - name: Run Migrations
-        env:
+        run: ./bin/migrate up -config config.json
-          DATABASE_URL: ${{ secrets.DATABASE_URL }}
-        run: ./bin/migrate up
       
       - name: Deploy
         run: ./bin/server
@@ -500,11 +497,11 @@ go build -o bin/migrate cmd/migrate/main.go
 ### 3. 生产环境
 
 - 编译后部署，先执行迁移再启动应用
-- 使用环境变量管理敏感信息
+- 使用配置文件管理敏感信息
 
 ```bash
 go build -o bin/migrate cmd/migrate/main.go
-DATABASE_URL="mysql://..." ./bin/migrate up
+./bin/migrate up -config config.json
 ./bin/server
 ```
 

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
+    // 使用factory的黑盒方法获取中间件链
-    logger, _ := fac.GetLogger()
+    // 自动从配置文件读取并配置所有中间件
-    defer logger.Close()
+    chain := fac.GetMiddlewareChain()
     
-    // 配置中间件链
+    // （可选）如果项目需要额外的中间件，可以继续添加
-    chain := middleware.NewChain(
+    // chain.Append(yourAuthMiddleware, yourMetricsMiddleware)
-        middleware.Recovery(&middleware.RecoveryConfig{Logger: logger}),
-        middleware.Logging(&middleware.LoggingConfig{Logger: logger}),
-        middleware.RateLimitByIP(100, time.Minute),
-        middleware.CORS(nil),
-        middleware.Timezone,
-    )
     
     // 注册路由
     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{
+chain := fac.GetMiddlewareChain()
-    Limiter: limiter,
+
-    KeyFunc: func(r *http.Request) string {
+// 添加自定义中间件
-        return r.Header.Get("X-User-ID")
+chain.Append(
-    },
+    yourAuthMiddleware,      // 认证中间件
-}
+    yourMetricsMiddleware,   // 指标中间件
-chain := middleware.NewChain(
+    // 更多自定义中间件...
-    middleware.RateLimit(rateLimitConfig),
 )
+
+// 使用扩展后的中间件链
+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 的基本使用。

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()
+    chain := fac.GetMiddlewareChain()
-    defer logger.Close()
     
-    // 配置中间件
+    // （可选）添加自定义中间件
-    chain := middleware.NewChain(
+    chain.Append(yourAuthMiddleware)
-        middleware.Recovery(&middleware.RecoveryConfig{Logger: logger}),
-        middleware.Logging(&middleware.LoggingConfig{Logger: logger}),
-        middleware.RateLimitByIP(100, time.Minute),
-        middleware.CORS(nil),
-        middleware.Timezone,
-    )
     
-    // 注册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
 ```
 
-## 使用示例
+## 核心功能示例
 
-详细的使用说明请参考各模块的文档：
+详细文档请参考：[完整文档](./docs/README.md) | [快速开始](./QUICKSTART.md)
-- **[数据库迁移完整指南](./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)
 
-### 快速示例
+### 数据库迁移
-
-#### 数据库迁移（独立工具，零耦合）⭐
 ```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黑盒模式）
+更多示例：[examples目录](./examples/)
-```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/) 目录。
 
 ## 版本管理
 
@@ -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,      // 最大连接数
+        "maxOpenConns": 100,     // 连接池配置
-        "maxIdleConns": 10,       // 最大空闲连接
+        "maxIdleConns": 10,
-        "connMaxLifetime": 3600   // 连接最大生存时间（秒）
+        "connMaxLifetime": 3600
+    },
+    "rateLimit": {
+        "enable": true,          // 开启限流
+        "rate": 100,
+        "period": 60,
+        "byIP": true
     }
 }
 ```
 
+### 使用建议
+- ✅ 使用工厂黑盒模式，减少重复代码
+- ✅ 生产环境开启异步日志和限流
+- ✅ 配置Recovery中间件防止panic
+- ✅ 明确指定CORS允许的源
+- ❌ 避免在循环中创建logger
+- ❌ 避免使用同步日志记录大量日志
+
 ## 故障排除
 
-### 问题1：循环导入错误
+常见问题请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
-
-**错误**：`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)
 
 ## 贡献指南
 

config/config.go

@@ -9,14 +9,15 @@ import (
 
 // Config 应用配置
 type Config struct {
-	Database *DatabaseConfig `json:"database"`
+	Database  *DatabaseConfig  `json:"database"`
-	OSS      *OSSConfig      `json:"oss"`
+	OSS       *OSSConfig       `json:"oss"`
-	Redis    *RedisConfig    `json:"redis"`
+	Redis     *RedisConfig     `json:"redis"`
-	CORS     *CORSConfig     `json:"cors"`
+	CORS      *CORSConfig      `json:"cors"`
-	MinIO    *MinIOConfig    `json:"minio"`
+	MinIO     *MinIOConfig     `json:"minio"`
-	Email    *EmailConfig    `json:"email"`
+	Email     *EmailConfig     `json:"email"`
-	SMS      *SMSConfig      `json:"sms"`
+	SMS       *SMSConfig       `json:"sms"`
-	Logger   *LoggerConfig   `json:"logger"`
+	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 获取数据库配置

config/example.json

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

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. 创建工厂（推荐）

docs/migration.md

@@ -13,7 +13,101 @@
 - 自动创建迁移记录表
 - 事务支持，确保迁移的原子性
 
-## 使用方法
+## 🚀 最简单的使用方式（黑盒模式，推荐）
+
+这是最简单的迁移方式，内部自动处理配置加载、数据库连接、迁移执行等所有细节。
+
+### 方式一：使用独立迁移工具（推荐）
+
+1. **复制迁移工具模板到你的项目**：
+
+```bash
+mkdir -p cmd/migrate
+cp /path/to/go-common/templates/migrate/main.go cmd/migrate/
+```
+
+2. **创建迁移文件**：
+
+```bash
+mkdir -p migrations
+# 或使用其他目录，如 scripts/sql
+```
+
+创建 `migrations/01_init_schema.sql`：
+
+```sql
+CREATE TABLE users (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+3. **编译和使用**：
+
+```bash
+# 编译
+go build -o bin/migrate cmd/migrate/main.go
+
+# 使用（最简单，使用默认配置和默认迁移目录）
+./bin/migrate up
+
+# 指定配置文件
+./bin/migrate up -config config.json
+
+# 指定配置和迁移目录
+./bin/migrate up -config config.json -dir scripts/sql
+
+# 查看状态
+./bin/migrate status
+
+# 回滚
+./bin/migrate down
+```
+
+**特点**：
+- ✅ 零配置：使用默认值即可运行
+- ✅ 自动查找配置：支持环境变量、默认路径
+- ✅ 自动处理：配置加载、数据库连接、迁移执行全自动
+
+### 方式二：在代码中直接调用（简单场景）
+
+```go
+import "git.toowon.com/jimmy/go-common/migration"
+
+// 最简单：使用默认配置和默认迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("", "", "up")
+
+// 指定配置文件，使用默认迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
+
+// 指定配置和迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
+
+// 查看状态
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "migrations", "status")
+```
+
+**参数说明**：
+- `configFile`: 配置文件路径，空字符串时自动查找（config.json, ../config.json）
+- `migrationsDir`: 迁移文件目录，空字符串时使用默认值 "migrations"
+- `command`: 命令，支持 "up", "down", "status"
+
+### 方式三：使用Factory（如果项目已使用Factory）
+
+```go
+import "git.toowon.com/jimmy/go-common/factory"
+
+fac, _ := factory.NewFactoryFromFile("config.json")
+// 使用默认目录 "migrations"
+err := fac.RunMigrations()
+// 或指定目录
+err := fac.RunMigrations("scripts/sql")
+```
+
+---
+
+## 详细使用方法（高级功能）
 
 ### 1. 创建迁移器
 
@@ -86,14 +180,16 @@ migrations := []migration.Migration{
 migrator.AddMigrations(migrations...)
 ```
 
-#### 方式三：从文件加载迁移
+#### 方式三：从文件加载迁移（推荐）
 
 ```go
-// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
+// 支持的文件命名格式：
-// 例如: 20240101000001_create_users_table.up.sql
+//   1. 数字前缀: 01_init_schema.sql
-// 对应的回滚文件: 20240101000001_create_users_table.down.sql
+//   2. 时间戳: 20240101000001_create_users.sql
+//   3. 带.up后缀: 20240101000001_create_users.up.sql
+//   对应的回滚文件: 20240101000001_create_users.down.sql
 
-migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.up.sql")
+migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.sql")
 if err != nil {
     log.Fatal(err)
 }
@@ -101,6 +197,12 @@ if err != nil {
 migrator.AddMigrations(migrations...)
 ```
 
+**新特性：**
+- ✅ 支持数字前缀命名（如 `01_init_schema.sql`）
+- ✅ 自动分割多行 SQL 语句
+- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
+- ✅ 记录执行时间（毫秒）
+
 ### 3. 执行迁移
 
 ```go
@@ -289,15 +391,31 @@ type MigrationStatus struct {
 
 **参数：**
 - `dir`: 迁移文件目录
-- `pattern`: 文件匹配模式，如 "*.up.sql"
+- `pattern`: 文件匹配模式，如 "*.sql" 或 "*.up.sql"
 
 **返回：** 迁移列表和错误信息
 
-**文件命名格式：** `{version}_{description}.up.sql`
+**支持的文件命名格式：**
 
-**示例：**
+1. **数字前缀格式**（新支持）：
-- `20240101000001_create_users_table.up.sql` - 升级文件
+   - `01_init_schema.sql`
-- `20240101000001_create_users_table.down.sql` - 回滚文件（可选）
+   - `02_init_data.sql`
+   - `03_add_log_schema.sql`
+
+2. **时间戳格式**（现有）：
+   - `20240101000001_create_users.sql`
+   - `20240101000002_add_index.sql`
+
+3. **带.up后缀格式**（现有）：
+   - `20240101000001_create_users.up.sql` - 升级文件
+   - `20240101000001_create_users.down.sql` - 回滚文件（可选）
+
+**新特性：**
+- ✅ 自动识别文件命名格式（数字前缀或时间戳）
+- ✅ 自动分割多行 SQL 语句（按分号分割）
+- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
+- ✅ 自动跳过空行和空白字符
+- ✅ 支持一个文件包含多个 SQL 语句
 
 #### GenerateVersion() string
 

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,
+		}, "请求指标")
+	})
+}

examples/factory_example.go

@@ -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("示例执行完成")
-}

examples/middleware_full_example.go

@@ -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"))
-}
-

examples/middleware_ratelimit_example.go

@@ -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))
-}
-

examples/migration_example.go

@@ -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)
-	}
-}
-

examples/migration_reset_example.go

@@ -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.")
-}
-

examples/migrations/README.md

@@ -110,10 +110,14 @@ func main() {
 }
 ```
 
-### 方式2：环境变量（Docker友好）
+### 方式2：使用配置文件（推荐）
 
 ```bash
-DATABASE_URL="mysql://root:password@localhost:3306/mydb" go run migrate.go up
+# 使用默认配置文件 config.json
+go run migrate.go up
+
+# 或指定配置文件路径
+go run migrate.go up -config /path/to/config.json
 ```
 
 **Docker 中**：
@@ -121,12 +125,13 @@ DATABASE_URL="mysql://root:password@localhost:3306/mydb" go run migrate.go up
 # docker-compose.yml
 services:
   app:
-    environment:
+    volumes:
-      DATABASE_URL: mysql://root:password@db:3306/mydb
+      # 挂载配置文件
+      - ./config.json:/app/config.json:ro
     command: sh -c "go run migrate.go up && ./app"
 ```
 
-**注意**：Docker 中使用服务名（`db`），不是 `localhost`
+**注意**：配置文件中的数据库主机应使用服务名（`db`），不是 `localhost`
 
 ## 更多信息
 

factory/factory.go

@@ -4,11 +4,14 @@ 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/migration"
 	"git.toowon.com/jimmy/go-common/sms"
 	"git.toowon.com/jimmy/go-common/storage"
 	"github.com/redis/go-redis/v9"
@@ -18,6 +21,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 +103,8 @@ func (f *Factory) getEmailClient() (*email.Email, error) {
 	return e, nil
 }
 
-// SendEmail 发送邮件（黑盒模式）
+// SendEmail 发送邮件（黑盒模式，推荐使用）
+// 自动使用配置文件中的SMTP配置发送邮件
 // to: 收件人列表
 // subject: 邮件主题
 // body: 邮件正文（纯文本）
@@ -108,7 +147,8 @@ func (f *Factory) getSMSClient() (*sms.SMS, error) {
 	return s, nil
 }
 
-// SendSMS 发送短信（黑盒模式）
+// SendSMS 发送短信（黑盒模式，推荐使用）
+// 自动使用配置文件中的阿里云短信配置发送短信
 // phoneNumbers: 手机号列表
 // templateParam: 模板参数（map或JSON字符串）
 // templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
@@ -153,15 +193,31 @@ func (f *Factory) getLogger() (*logger.Logger, error) {
 	return l, nil
 }
 
-// GetLogger 获取日志记录器对象（已初始化）
+// GetLogger 获取日志记录器对象（不推荐直接使用）
-// 返回已初始化的日志记录器对象，可直接使用
+//
-// 注意：推荐使用 LogDebug、LogInfo、LogWarn、LogError 等方法直接记录日志
+// ⚠️  不推荐直接使用此方法，推荐使用黑盒方法：
-// 如果需要使用logger的高级功能（如Close方法），可以使用此方法获取logger对象
+//   - 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 +238,8 @@ func (f *Factory) LogDebug(message string, args ...interface{}) {
 	}
 }
 
-// LogDebugf 记录调试日志（带字段）
+// LogDebugf 记录调试日志（带字段，黑盒模式，推荐使用）
+// 自动使用配置文件中的logger配置
 // fields: 日志字段
 // message: 日志消息
 // args: 格式化参数（可选）
@@ -200,7 +257,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 +279,8 @@ func (f *Factory) LogInfo(message string, args ...interface{}) {
 	}
 }
 
-// LogInfof 记录信息日志（带字段）
+// LogInfof 记录信息日志（带字段，黑盒模式，推荐使用）
+// 自动使用配置文件中的logger配置
 // fields: 日志字段
 // message: 日志消息
 // args: 格式化参数（可选）
@@ -239,7 +298,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 +320,8 @@ func (f *Factory) LogWarn(message string, args ...interface{}) {
 	}
 }
 
-// LogWarnf 记录警告日志（带字段）
+// LogWarnf 记录警告日志（带字段，黑盒模式，推荐使用）
+// 自动使用配置文件中的logger配置
 // fields: 日志字段
 // message: 日志消息
 // args: 格式化参数（可选）
@@ -278,7 +339,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 +361,8 @@ func (f *Factory) LogError(message string, args ...interface{}) {
 	}
 }
 
-// LogErrorf 记录错误日志（带字段）
+// LogErrorf 记录错误日志（带字段，黑盒模式，推荐使用）
+// 自动使用配置文件中的logger配置
 // fields: 日志字段
 // message: 日志消息
 // args: 格式化参数（可选）
@@ -370,9 +433,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 +512,35 @@ func (f *Factory) getRedisClient() (*redis.Client, error) {
 	return client, nil
 }
 
-// GetRedisClient 获取Redis客户端对象（已初始化）
+// GetRedisClient 获取Redis客户端对象（高级功能时使用）
-// 返回已初始化的Redis客户端对象，可直接使用
+// 返回已初始化的Redis客户端对象
-// 注意：推荐使用 RedisGet、RedisSet、RedisDelete 等方法直接操作Redis
+//
-// 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
+// ℹ️  推荐使用黑盒方法：
+//   - 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 +559,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 +583,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 +604,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 +653,8 @@ func (f *Factory) getStorage() (storage.Storage, error) {
 	return s, nil
 }
 
-// UploadFile 上传文件
+// UploadFile 上传文件（黑盒模式，推荐使用）
+// 自动根据配置选择存储类型（OSS 或 MinIO），无需关心内部实现
 // ctx: 上下文
 // objectKey: 对象键（文件路径）
 // reader: 文件内容
@@ -583,8 +681,9 @@ func (f *Factory) UploadFile(ctx context.Context, objectKey string, reader io.Re
 	return url, nil
 }
 
-// GetFileURL 获取文件访问URL（Show方法）
+// GetFileURL 获取文件访问URL（黑盒模式，推荐使用）
-// objectKey: 对象键
+// 自动根据配置选择存储类型，返回文件的访问URL
+// objectKey: 对象键（文件路径）
 // expires: 过期时间（秒），0表示永久有效
 func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
 	s, err := f.getStorage()
@@ -594,3 +693,172 @@ 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...)
+}
+
+// RunMigrations 执行数据库迁移（黑盒模式，推荐使用）
+// 自动发现并执行指定目录下的所有迁移文件
+// migrationsDir: 迁移文件目录（如 "migrations" 或 "scripts/sql"）
+//
+// 支持的文件命名格式：
+//   - 数字前缀: 01_init_schema.sql
+//   - 时间戳: 20240101000001_create_users.sql
+//   - 带.up后缀: 20240101000001_create_users.up.sql
+//
+// 示例：
+//
+//	fac, _ := factory.NewFactoryFromFile("config.json")
+//	err := fac.RunMigrations("migrations")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+func (f *Factory) RunMigrations(migrationsDir string) error {
+	// 获取数据库连接
+	db, err := f.getDatabase()
+	if err != nil {
+		return fmt.Errorf("failed to get database: %w", err)
+	}
+
+	// 创建迁移器（传入数据库类型，性能更好）
+	dbType := "mysql" // 默认值
+	if f.cfg.Database != nil && f.cfg.Database.Type != "" {
+		dbType = f.cfg.Database.Type
+	}
+	migrator := migration.NewMigratorWithType(db, dbType)
+
+	// 自动发现并加载迁移文件
+	migrations, err := migration.LoadMigrationsFromFiles(migrationsDir, "*.sql")
+	if err != nil {
+		return fmt.Errorf("failed to load migrations: %w", err)
+	}
+
+	if len(migrations) == 0 {
+		f.LogInfo("在目录 '%s' 中没有找到迁移文件", migrationsDir)
+		return nil
+	}
+
+	migrator.AddMigrations(migrations...)
+
+	// 执行迁移
+	if err := migrator.Up(); err != nil {
+		return fmt.Errorf("failed to run migrations: %w", err)
+	}
+
+	f.LogInfo("迁移执行成功: %d 个迁移文件", len(migrations))
+	return nil
+}
+
+// GetMigrationStatus 获取迁移状态（黑盒模式，推荐使用）
+// migrationsDir: 迁移文件目录
+// 返回迁移状态列表，包含版本、描述、是否已应用等信息
+//
+// 示例：
+//
+//	fac, _ := factory.NewFactoryFromFile("config.json")
+//	status, err := fac.GetMigrationStatus("migrations")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	for _, s := range status {
+//	    fmt.Printf("Version: %s, Applied: %v\n", s.Version, s.Applied)
+//	}
+func (f *Factory) GetMigrationStatus(migrationsDir string) ([]migration.MigrationStatus, error) {
+	// 获取数据库连接
+	db, err := f.getDatabase()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get database: %w", err)
+	}
+
+	// 创建迁移器（传入数据库类型，性能更好）
+	dbType := "mysql" // 默认值
+	if f.cfg.Database != nil && f.cfg.Database.Type != "" {
+		dbType = f.cfg.Database.Type
+	}
+	migrator := migration.NewMigratorWithType(db, dbType)
+
+	// 加载迁移文件
+	migrations, err := migration.LoadMigrationsFromFiles(migrationsDir, "*.sql")
+	if err != nil {
+		return nil, fmt.Errorf("failed to load migrations: %w", err)
+	}
+
+	migrator.AddMigrations(migrations...)
+
+	// 获取状态
+	status, err := migrator.Status()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get migration status: %w", err)
+	}
+
+	return status, nil
+}

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 != "" {

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)
 		},
 	})
 }

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),
 	}
 

migration/helper.go

@@ -25,46 +25,38 @@ import (
 //
 //	import "git.toowon.com/jimmy/go-common/migration"
 //	migration.RunMigrationsFromConfig("config.json", "migrations")
+//	// 或使用默认迁移目录
+//	migration.RunMigrationsFromConfig("config.json", "")
 func RunMigrationsFromConfig(configFile, migrationsDir string) error {
-	// 加载配置
+	return RunMigrationsFromConfigWithCommand(configFile, migrationsDir, "up")
-	cfg, err := loadConfigFromFileOrEnv(configFile)
-	if err != nil {
-		return fmt.Errorf("加载配置失败: %w", err)
-	}
-
-	// 连接数据库
-	db, err := connectDB(cfg)
-	if err != nil {
-		return fmt.Errorf("连接数据库失败: %w", err)
-	}
-
-	// 创建迁移器
-	migrator := NewMigrator(db)
-
-	// 加载迁移文件
-	migrations, err := LoadMigrationsFromFiles(migrationsDir, "*.sql")
-	if err != nil {
-		return fmt.Errorf("加载迁移文件失败: %w", err)
-	}
-
-	if len(migrations) == 0 {
-		fmt.Printf("在目录 '%s' 中没有找到迁移文件\n", migrationsDir)
-		return nil
-	}
-
-	migrator.AddMigrations(migrations...)
-
-	// 执行迁移
-	if err := migrator.Up(); err != nil {
-		return fmt.Errorf("执行迁移失败: %w", err)
-	}
-
-	fmt.Println("✓ 迁移执行成功")
-	return nil
 }
 
-// RunMigrationsFromConfigWithCommand 从配置文件运行迁移（支持命令）
+// RunMigrationsFromConfigWithCommand 从配置文件运行迁移（支持命令，黑盒模式）
-// command: "up", "down", "status"
+//
+// 这是最简单的迁移方式，内部自动处理：
+// - 配置加载（支持配置文件、默认路径）
+// - 数据库连接（自动识别数据库类型）
+// - 迁移文件加载和执行
+//
+// 参数：
+//   - configFile: 配置文件路径，支持：
+//   - 空字符串：自动查找（config.json, ../config.json）
+//   - 相对路径或绝对路径：指定配置文件路径
+//   - migrationsDir: 迁移文件目录，支持：
+//   - 空字符串：使用默认目录 "migrations"
+//   - 相对路径或绝对路径
+//   - command: 命令，支持 "up", "down", "status"
+//
+// 使用示例：
+//
+//	// 最简单：使用默认配置和默认迁移目录
+//	migration.RunMigrationsFromConfigWithCommand("", "", "up")
+//
+//	// 指定配置文件，使用默认迁移目录
+//	migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
+//
+//	// 指定配置和迁移目录
+//	migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
 func RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command string) error {
 	// 加载配置
 	cfg, err := loadConfigFromFileOrEnv(configFile)
@@ -78,8 +70,13 @@ func RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command strin
 		return fmt.Errorf("连接数据库失败: %w", err)
 	}
 
-	// 创建迁移器
+	// 使用默认迁移目录（如果未指定）
-	migrator := NewMigrator(db)
+	if migrationsDir == "" {
+		migrationsDir = "migrations"
+	}
+
+	// 创建迁移器（传入数据库类型，性能更好）
+	migrator := NewMigratorWithType(db, cfg.Database.Type)
 
 	// 加载迁移文件
 	migrations, err := LoadMigrationsFromFiles(migrationsDir, "*.sql")
@@ -122,22 +119,16 @@ func RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command strin
 	return nil
 }
 
-// loadConfigFromFileOrEnv 从文件或环境变量加载配置
+// loadConfigFromFileOrEnv 从配置文件加载配置
+// 支持指定配置文件路径，或自动查找默认路径
 func loadConfigFromFileOrEnv(configFile string) (*config.Config, error) {
-	// 优先从环境变量加载
+	// 如果指定了配置文件路径，优先使用
-	if dbURL := os.Getenv("DATABASE_URL"); dbURL != "" {
-		return &config.Config{
-			Database: &config.DatabaseConfig{
-				DSN: dbURL,
-			},
-		}, nil
-	}
-
-	// 尝试从配置文件加载
 	if configFile != "" {
 		if _, err := os.Stat(configFile); err == nil {
 			return config.LoadFromFile(configFile)
 		}
+		// 如果指定的文件不存在，返回错误
+		return nil, fmt.Errorf("配置文件不存在: %s", configFile)
 	}
 
 	// 尝试默认路径
@@ -148,10 +139,11 @@ func loadConfigFromFileOrEnv(configFile string) (*config.Config, error) {
 		}
 	}
 
-	return nil, fmt.Errorf("未找到配置文件，也未设置环境变量 DATABASE_URL")
+	return nil, fmt.Errorf("未找到配置文件，请指定配置文件路径或确保存在以下文件之一: %v", defaultPaths)
 }
 
 // connectDB 连接数据库
+// 与 factory.getDatabase 保持一致的实现，避免代码重复
 func connectDB(cfg *config.Config) (*gorm.DB, error) {
 	if cfg.Database == nil {
 		return nil, fmt.Errorf("数据库配置为空")
@@ -178,15 +170,30 @@ func connectDB(cfg *config.Config) (*gorm.DB, error) {
 		return nil, err
 	}
 
-	// 配置连接池
+	// 配置连接池（与 factory.getDatabase 保持一致）
 	sqlDB, err := db.DB()
 	if err != nil {
 		return nil, err
 	}
 
-	sqlDB.SetMaxOpenConns(10)
+	// 使用配置文件中的连接池参数，如果没有配置则使用默认值
-	sqlDB.SetMaxIdleConns(5)
+	if cfg.Database.MaxOpenConns > 0 {
-	sqlDB.SetConnMaxLifetime(time.Hour)
+		sqlDB.SetMaxOpenConns(cfg.Database.MaxOpenConns)
+	} else {
+		sqlDB.SetMaxOpenConns(10) // 默认值
+	}
+
+	if cfg.Database.MaxIdleConns > 0 {
+		sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
+	} else {
+		sqlDB.SetMaxIdleConns(5) // 默认值
+	}
+
+	if cfg.Database.ConnMaxLifetime > 0 {
+		sqlDB.SetConnMaxLifetime(time.Duration(cfg.Database.ConnMaxLifetime) * time.Second)
+	} else {
+		sqlDB.SetConnMaxLifetime(time.Hour) // 默认值
+	}
 
 	return db, nil
 }
@@ -213,4 +220,3 @@ func printMigrationStatus(status []MigrationStatus) {
 	fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
 	fmt.Println()
 }
-

migration/migration.go

@@ -26,6 +26,7 @@ type Migrator struct {
 	db         *gorm.DB
 	migrations []Migration
 	tableName  string
+	dbType     string // 数据库类型: mysql, postgres, sqlite
 }
 
 // NewMigrator 创建新的迁移器
@@ -41,6 +42,25 @@ func NewMigrator(db *gorm.DB, tableName ...string) *Migrator {
 		db:         db,
 		migrations: make([]Migration, 0),
 		tableName:  table,
+		dbType:     "", // 未指定时为空，会使用兼容模式
+	}
+}
+
+// NewMigratorWithType 创建新的迁移器（指定数据库类型，性能更好）
+// db: GORM数据库连接
+// dbType: 数据库类型 ("mysql", "postgres", "sqlite")
+// tableName: 存储迁移记录的表名，默认为 "schema_migrations"
+func NewMigratorWithType(db *gorm.DB, dbType string, tableName ...string) *Migrator {
+	table := "schema_migrations"
+	if len(tableName) > 0 && tableName[0] != "" {
+		table = tableName[0]
+	}
+
+	return &Migrator{
+		db:         db,
+		migrations: make([]Migration, 0),
+		tableName:  table,
+		dbType:     dbType,
 	}
 }
 
@@ -56,33 +76,152 @@ func (m *Migrator) AddMigrations(migrations ...Migration) {
 
 // initTable 初始化迁移记录表
 func (m *Migrator) initTable() error {
-	// 检查表是否存在
+	// 检查表是否存在（根据数据库类型使用对应的SQL，性能更好）
 	var exists bool
-	err := m.db.Raw(fmt.Sprintf(`
+	var err error
-		SELECT EXISTS (
-			SELECT FROM information_schema.tables 
-			WHERE table_schema = CURRENT_SCHEMA() 
-			AND table_name = '%s'
-		)
-	`, m.tableName)).Scan(&exists).Error
 
+	switch m.dbType {
+	case "mysql":
+		// MySQL/MariaDB语法
+		var count int64
+		err = m.db.Raw(fmt.Sprintf(`
+			SELECT COUNT(*) FROM information_schema.tables 
+			WHERE table_schema = DATABASE() 
+			AND table_name = '%s'
+		`, m.tableName)).Scan(&count).Error
+		if err == nil {
+			exists = count > 0
+		}
+	case "postgres":
+		// PostgreSQL语法
+		err = m.db.Raw(fmt.Sprintf(`
+			SELECT EXISTS (
+				SELECT 1 FROM information_schema.tables 
+				WHERE table_schema = CURRENT_SCHEMA() 
+				AND table_name = '%s'
+			)
+		`, m.tableName)).Scan(&exists).Error
+	case "sqlite":
+		// SQLite语法
+		var count int64
+		err = m.db.Raw(fmt.Sprintf(`
+			SELECT COUNT(*) FROM sqlite_master 
+			WHERE type='table' AND name='%s'
+		`, m.tableName)).Scan(&count).Error
+		if err == nil {
+			exists = count > 0
+		}
+	default:
+		// 未指定数据库类型时，使用兼容模式（向后兼容）
+		// 按顺序尝试不同数据库的语法
+		var count int64
+		err = m.db.Raw(fmt.Sprintf(`
+			SELECT COUNT(*) FROM information_schema.tables 
+			WHERE table_schema = DATABASE() 
+			AND table_name = '%s'
+		`, m.tableName)).Scan(&count).Error
+		if err == nil && count > 0 {
+			exists = true
+		} else {
+			var pgExists bool
+			err = m.db.Raw(fmt.Sprintf(`
+				SELECT EXISTS (
+					SELECT 1 FROM information_schema.tables 
+					WHERE table_schema = CURRENT_SCHEMA() 
+					AND table_name = '%s'
+				)
+			`, m.tableName)).Scan(&pgExists).Error
+			if err == nil {
+				exists = pgExists
+			} else {
+				var sqliteCount int64
+				err = m.db.Raw(fmt.Sprintf(`
+					SELECT COUNT(*) FROM sqlite_master 
+					WHERE type='table' AND name='%s'
+				`, m.tableName)).Scan(&sqliteCount).Error
+				if err == nil && sqliteCount > 0 {
+					exists = true
+				}
+			}
+		}
+	}
+
+	// 如果查询失败，假设表不存在，尝试创建
 	if err != nil {
-		// 如果查询失败，可能是SQLite或其他数据库，尝试直接创建
 		exists = false
 	}
 
 	if !exists {
-		// 创建迁移记录表
+		// 创建迁移记录表（包含执行时间字段）
 		err = m.db.Exec(fmt.Sprintf(`
 			CREATE TABLE IF NOT EXISTS %s (
 				version VARCHAR(255) PRIMARY KEY,
 				description VARCHAR(255),
-				applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+				applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+				execution_time INT COMMENT '执行耗时(ms)'
 			)
 		`, m.tableName)).Error
 		if err != nil {
 			return fmt.Errorf("failed to create migration table: %w", err)
 		}
+	} else {
+		// 表已存在，检查是否有 execution_time 字段（向后兼容）
+		// 注意：这个检查可能在某些数据库中失败，但不影响功能
+		// 如果字段不存在，记录执行时间时会失败，但不影响迁移执行
+		var hasExecutionTime bool
+		var columnCount int64
+		var checkErr error
+
+		switch m.dbType {
+		case "mysql":
+			// MySQL/MariaDB语法
+			checkErr = m.db.Raw(fmt.Sprintf(`
+				SELECT COUNT(*) 
+				FROM information_schema.columns 
+				WHERE table_schema = DATABASE() 
+				AND table_name = '%s' 
+				AND column_name = 'execution_time'
+			`, m.tableName)).Scan(&columnCount).Error
+			if checkErr == nil {
+				hasExecutionTime = columnCount > 0
+			}
+		case "postgres":
+			// PostgreSQL语法
+			checkErr = m.db.Raw(fmt.Sprintf(`
+				SELECT COUNT(*) 
+				FROM information_schema.columns 
+				WHERE table_schema = CURRENT_SCHEMA() 
+				AND table_name = '%s' 
+				AND column_name = 'execution_time'
+			`, m.tableName)).Scan(&columnCount).Error
+			if checkErr == nil {
+				hasExecutionTime = columnCount > 0
+			}
+		case "sqlite":
+			// SQLite不支持information_schema，跳过检查
+			hasExecutionTime = false
+		default:
+			// 兼容模式：尝试MySQL语法
+			checkErr = m.db.Raw(fmt.Sprintf(`
+				SELECT COUNT(*) 
+				FROM information_schema.columns 
+				WHERE table_schema = DATABASE() 
+				AND table_name = '%s' 
+				AND column_name = 'execution_time'
+			`, m.tableName)).Scan(&columnCount).Error
+			if checkErr == nil {
+				hasExecutionTime = columnCount > 0
+			}
+		}
+
+		if !hasExecutionTime {
+			// 尝试添加字段（如果失败不影响功能）
+			// 注意：SQLite的ALTER TABLE ADD COLUMN语法略有不同，但GORM会处理
+			_ = m.db.Exec(fmt.Sprintf(`
+				ALTER TABLE %s 
+				ADD COLUMN execution_time INT
+			`, m.tableName))
+		}
 	}
 
 	return nil
@@ -109,17 +248,34 @@ func (m *Migrator) getAppliedMigrations() (map[string]bool, error) {
 }
 
 // recordMigration 记录迁移
-func (m *Migrator) recordMigration(version, description string, isUp bool) error {
+func (m *Migrator) recordMigration(version, description string, isUp bool, executionTime ...int) error {
 	if err := m.initTable(); err != nil {
 		return err
 	}
 
 	if isUp {
-		// 记录迁移
+		// 记录迁移（包含执行时间，如果提供了）
-		err := m.db.Exec(fmt.Sprintf(`
+		var err error
-			INSERT INTO %s (version, description, applied_at) 
+		if len(executionTime) > 0 && executionTime[0] > 0 {
-			VALUES (?, ?, ?)
+			// 尝试插入执行时间（如果字段存在）
-		`, m.tableName), version, description, time.Now()).Error
+			err = m.db.Exec(fmt.Sprintf(`
+				INSERT INTO %s (version, description, applied_at, execution_time) 
+				VALUES (?, ?, ?, ?)
+			`, m.tableName), version, description, time.Now(), executionTime[0]).Error
+			if err != nil {
+				// 如果失败（可能是字段不存在），尝试不包含执行时间
+				err = m.db.Exec(fmt.Sprintf(`
+					INSERT INTO %s (version, description, applied_at) 
+					VALUES (?, ?, ?)
+				`, m.tableName), version, description, time.Now()).Error
+			}
+		} else {
+			// 不包含执行时间
+			err = m.db.Exec(fmt.Sprintf(`
+				INSERT INTO %s (version, description, applied_at) 
+				VALUES (?, ?, ?)
+			`, m.tableName), version, description, time.Now()).Error
+		}
 		if err != nil {
 			return fmt.Errorf("failed to record migration: %w", err)
 		}
@@ -160,6 +316,9 @@ func (m *Migrator) Up() error {
 			return fmt.Errorf("migration %s has no Up function", migration.Version)
 		}
 
+		// 记录开始时间
+		startTime := time.Now()
+
 		// 开始事务
 		tx := m.db.Begin()
 		if tx.Error != nil {
@@ -172,8 +331,11 @@ func (m *Migrator) Up() error {
 			return fmt.Errorf("failed to apply migration %s: %w", migration.Version, err)
 		}
 
-		// 记录迁移
+		// 计算执行时间（毫秒）
-		if err := m.recordMigrationWithDB(tx, migration.Version, migration.Description, true); err != nil {
+		executionTime := int(time.Since(startTime).Milliseconds())
+
+		// 记录迁移（包含执行时间）
+		if err := m.recordMigrationWithDB(tx, migration.Version, migration.Description, true, executionTime); err != nil {
 			tx.Rollback()
 			return err
 		}
@@ -183,7 +345,7 @@ func (m *Migrator) Up() error {
 			return fmt.Errorf("failed to commit migration %s: %w", migration.Version, err)
 		}
 
-		fmt.Printf("Applied migration: %s - %s\n", migration.Version, migration.Description)
+		fmt.Printf("Applied migration: %s - %s (耗时: %dms)\n", migration.Version, migration.Description, executionTime)
 	}
 
 	return nil
@@ -246,12 +408,29 @@ func (m *Migrator) Down() error {
 }
 
 // recordMigrationWithDB 使用指定的数据库连接记录迁移
-func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool) error {
+func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool, executionTime ...int) error {
 	if isUp {
-		err := db.Exec(fmt.Sprintf(`
+		var err error
-			INSERT INTO %s (version, description, applied_at) 
+		if len(executionTime) > 0 && executionTime[0] > 0 {
-			VALUES (?, ?, ?)
+			// 尝试插入执行时间（如果字段存在）
-		`, m.tableName), version, description, time.Now()).Error
+			err = db.Exec(fmt.Sprintf(`
+				INSERT INTO %s (version, description, applied_at, execution_time) 
+				VALUES (?, ?, ?, ?)
+			`, m.tableName), version, description, time.Now(), executionTime[0]).Error
+			if err != nil {
+				// 如果失败（可能是字段不存在），尝试不包含执行时间
+				err = db.Exec(fmt.Sprintf(`
+					INSERT INTO %s (version, description, applied_at) 
+					VALUES (?, ?, ?)
+				`, m.tableName), version, description, time.Now()).Error
+			}
+		} else {
+			// 不包含执行时间
+			err = db.Exec(fmt.Sprintf(`
+				INSERT INTO %s (version, description, applied_at) 
+				VALUES (?, ?, ?)
+			`, m.tableName), version, description, time.Now()).Error
+		}
 		if err != nil {
 			return fmt.Errorf("failed to record migration: %w", err)
 		}
@@ -300,10 +479,96 @@ type MigrationStatus struct {
 	Applied     bool
 }
 
+// splitSQL 分割SQL语句，处理多行SQL、注释等
+// 支持单行注释（--）、多行注释（/* */）、按分号分割语句
+func splitSQL(content string) []string {
+	var statements []string
+	var current strings.Builder
+
+	lines := strings.Split(content, "\n")
+	inMultiLineComment := false
+
+	for _, line := range lines {
+		trimmedLine := strings.TrimSpace(line)
+
+		// 跳过空行
+		if trimmedLine == "" {
+			continue
+		}
+
+		// 处理多行注释
+		if strings.HasPrefix(trimmedLine, "/*") {
+			inMultiLineComment = true
+		}
+		if strings.HasSuffix(trimmedLine, "*/") {
+			inMultiLineComment = false
+			continue
+		}
+		if inMultiLineComment {
+			continue
+		}
+
+		// 跳过单行注释
+		if strings.HasPrefix(trimmedLine, "--") {
+			continue
+		}
+
+		// 添加到当前语句
+		current.WriteString(line)
+		current.WriteString("\n")
+
+		// 检查是否是完整语句（以分号结尾）
+		if strings.HasSuffix(trimmedLine, ";") {
+			stmt := strings.TrimSpace(current.String())
+			if stmt != "" && !strings.HasPrefix(stmt, "--") {
+				statements = append(statements, stmt)
+			}
+			current.Reset()
+		}
+	}
+
+	// 添加最后一个语句（如果没有分号结尾）
+	if current.Len() > 0 {
+		stmt := strings.TrimSpace(current.String())
+		if stmt != "" && !strings.HasPrefix(stmt, "--") {
+			statements = append(statements, stmt)
+		}
+	}
+
+	return statements
+}
+
+// parseMigrationFileName 解析迁移文件名，支持多种格式
+// 格式1: 数字前缀 - 01_init_schema.sql
+// 格式2: 时间戳 - 20240101000001_create_users.sql
+// 格式3: 带.up后缀 - 20240101000001_create_users.up.sql
+// 返回: (version, description, error)
+func parseMigrationFileName(baseName string) (string, string, error) {
+	// 移除扩展名
+	nameWithoutExt := strings.TrimSuffix(baseName, filepath.Ext(baseName))
+	// 移除 .up 后缀（如果存在）
+	nameWithoutExt = strings.TrimSuffix(nameWithoutExt, ".up")
+
+	// 解析版本号和描述
+	parts := strings.SplitN(nameWithoutExt, "_", 2)
+	if len(parts) < 2 {
+		// 如果只有一个部分，尝试作为版本号（向后兼容）
+		return nameWithoutExt, baseName, nil
+	}
+
+	version := parts[0]
+	description := strings.Join(parts[1:], "_")
+
+	return version, description, nil
+}
+
 // LoadMigrationsFromFiles 从文件系统加载迁移文件
 // dir: 迁移文件目录
 // pattern: 文件命名模式，例如 "*.sql" 或 "*.up.sql"
-// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
+// 文件命名格式支持:
+//   - 数字前缀: 01_init_schema.sql
+//   - 时间戳: 20240101000001_create_users.sql
+//   - 带.up后缀: 20240101000001_create_users.up.sql
 func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
 	files, err := filepath.Glob(filepath.Join(dir, pattern))
 	if err != nil {
@@ -313,19 +578,17 @@ func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
 	migrations := make([]Migration, 0)
 	for _, file := range files {
 		baseName := filepath.Base(file)
-		// 移除扩展名
-		nameWithoutExt := strings.TrimSuffix(baseName, filepath.Ext(baseName))
-		// 移除 .up 后缀（如果存在）
-		nameWithoutExt = strings.TrimSuffix(nameWithoutExt, ".up")
 
-		// 解析版本号和描述
+		// 跳过 .down.sql 文件（会在处理 .up.sql 或 .sql 时自动加载）
-		parts := strings.SplitN(nameWithoutExt, "_", 2)
+		if strings.HasSuffix(baseName, ".down.sql") {
-		if len(parts) < 2 {
+			continue
-			return nil, fmt.Errorf("invalid migration file name format: %s (expected: {version}_{description})", baseName)
 		}
 
-		version := parts[0]
+		// 解析版本号和描述
-		description := strings.Join(parts[1:], "_")
+		version, description, err := parseMigrationFileName(baseName)
+		if err != nil {
+			return nil, fmt.Errorf("invalid migration file name format: %s: %w", baseName, err)
+		}
 
 		// 读取文件内容
 		content, err := os.ReadFile(file)
@@ -343,26 +606,81 @@ func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
 			downSQL = string(downContent)
 		}
 
+		// 创建迁移，使用 SQL 分割功能
 		migration := Migration{
 			Version:     version,
 			Description: description,
 			Up: func(db *gorm.DB) error {
-				return db.Exec(sqlContent).Error
+				// 分割 SQL 语句
+				statements := splitSQL(sqlContent)
+				if len(statements) == 0 {
+					return nil // 空文件，跳过
+				}
+
+				// 执行每个 SQL 语句
+				// 注意：某些 DDL 语句（如 CREATE TABLE）在某些数据库中会隐式提交事务
+				// 因此这里不使用事务，而是逐个执行
+				for i, stmt := range statements {
+					stmt = strings.TrimSpace(stmt)
+					if stmt == "" {
+						continue
+					}
+
+					if err := db.Exec(stmt).Error; err != nil {
+						// 如果是表已存在的错误，记录警告但继续执行（向后兼容）
+						errStr := err.Error()
+						if strings.Contains(errStr, "already exists") ||
+							strings.Contains(errStr, "Duplicate") ||
+							strings.Contains(errStr, "duplicate") {
+							fmt.Printf("Warning: SQL statement %d in migration %s: %v\n", i+1, version, err)
+							continue
+						}
+						return fmt.Errorf("failed to execute SQL statement %d in migration %s: %w\nSQL: %s", i+1, version, err, stmt)
+					}
+				}
+
+				return nil
 			},
 		}
 
 		if downSQL != "" {
 			migration.Down = func(db *gorm.DB) error {
-				return db.Exec(downSQL).Error
+				// 分割 SQL 语句
+				statements := splitSQL(downSQL)
+				if len(statements) == 0 {
+					return nil
+				}
+
+				// 执行每个 SQL 语句
+				for i, stmt := range statements {
+					stmt = strings.TrimSpace(stmt)
+					if stmt == "" {
+						continue
+					}
+
+					if err := db.Exec(stmt).Error; err != nil {
+						return fmt.Errorf("failed to execute SQL statement %d in rollback %s: %w\nSQL: %s", i+1, version, err, stmt)
+					}
+				}
+
+				return nil
 			}
 		}
 
 		migrations = append(migrations, migration)
 	}
 
-	// 按版本号排序
+	// 按版本号排序（支持数字和时间戳混合排序）
 	sort.Slice(migrations, func(i, j int) bool {
-		return migrations[i].Version < migrations[j].Version
+		vi, vj := migrations[i].Version, migrations[j].Version
+		// 尝试按数字排序（如果是数字前缀）
+		if viNum, err1 := strconv.Atoi(vi); err1 == nil {
+			if vjNum, err2 := strconv.Atoi(vj); err2 == nil {
+				return viNum < vjNum
+			}
+		}
+		// 否则按字符串排序
+		return vi < vj
 	})
 
 	return migrations, nil

templates/migrate/main.go

@@ -24,11 +24,11 @@ import (
 //     ./migrate down                                  # 回滚最后一个迁移
 //
 //   Docker 中使用：
-//     # 方式1：挂载配置文件
+//     # 方式1：挂载配置文件（推荐）
 //     docker run -v /host/config.json:/app/config.json myapp ./migrate up
 //
-//     # 方式2：使用环境变量
+//     # 方式2：使用环境变量指定配置文件路径
-//     docker run -e DATABASE_URL="mysql://..." myapp ./migrate up
+//     docker run -e CONFIG_FILE=/etc/app/config.json myapp ./migrate up
 //
 //     # 方式3：指定容器内的配置文件路径
 //     docker run myapp ./migrate up -config /etc/app/config.json
@@ -41,8 +41,7 @@ import (
 // 配置优先级（从高到低）：
 //   1. 命令行参数 -config 和 -dir
 //   2. 环境变量 CONFIG_FILE 和 MIGRATIONS_DIR
-//   3. 环境变量 DATABASE_URL（直接连接，无需配置文件）
+//   3. 默认值（config.json 和 migrations）
-//   4. 默认值（config.json 和 migrations）
 
 var (
 	configFile    string
@@ -69,6 +68,9 @@ func main() {
 	}
 
 	// 获取命令（默认up）
+	// 支持两种方式：
+	// 1. 位置参数：./migrate up
+	// 2. 标志参数：./migrate -cmd=up（向后兼容）
 	command := "up"
 	args := flag.Args()
 	if len(args) > 0 {
@@ -83,16 +85,18 @@ func main() {
 	}
 
 	// 获取配置文件路径（优先级：命令行 > 环境变量 > 默认值）
+	// 如果未指定，RunMigrationsFromConfigWithCommand 会自动查找
 	if configFile == "" {
-		configFile = getEnv("CONFIG_FILE", "config.json")
+		configFile = getEnv("CONFIG_FILE", "")
 	}
 
 	// 获取迁移目录（优先级：命令行 > 环境变量 > 默认值）
+	// 如果未指定，RunMigrationsFromConfigWithCommand 会使用默认值 "migrations"
 	if migrationsDir == "" {
-		migrationsDir = getEnv("MIGRATIONS_DIR", "migrations")
+		migrationsDir = getEnv("MIGRATIONS_DIR", "")
 	}
 
-	// 执行迁移
+	// 执行迁移（黑盒模式：内部自动处理所有细节）
 	if err := migration.RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command); err != nil {
 		fmt.Fprintf(os.Stderr, "错误: %v\n", err)
 		os.Exit(1)
@@ -132,16 +136,14 @@ func printHelp() {
 	fmt.Println("  # 指定配置和迁移目录")
 	fmt.Println("  migrate up -c config.json -d db/migrations")
 	fmt.Println()
-	fmt.Println("  # 使用环境变量")
+	fmt.Println("  # 使用环境变量指定配置文件路径")
-	fmt.Println("  DATABASE_URL='mysql://...' migrate up")
+	fmt.Println("  CONFIG_FILE=/etc/app/config.json migrate up")
 	fmt.Println()
-	fmt.Println("  # Docker 中使用")
+	fmt.Println("  # Docker 中使用（挂载配置文件）")
 	fmt.Println("  docker run -v /host/config.json:/app/config.json myapp migrate up")
 	fmt.Println()
 	fmt.Println("配置优先级（从高到低）:")
 	fmt.Println("  1. 命令行参数 -config 和 -dir")
 	fmt.Println("  2. 环境变量 CONFIG_FILE 和 MIGRATIONS_DIR")
-	fmt.Println("  3. 环境变量 DATABASE_URL")
+	fmt.Println("  3. 默认值（config.json 和 migrations）")
-	fmt.Println("  4. 默认值（config.json 和 migrations）")
 }
-