Gin中间件嵌套与分层设计

中间件分层设计是构建可维护Web应用的关键，合理的分层使职责清晰、易于扩展。

洋葱模型深入理解

执行顺序可视化

请求流向（从外向内）：
┌─────────────────────────────────────────────┐
│ Layer1: Recovery                            │ ← 全局错误处理
│ ┌─────────────────────────────────────────┐ │
│ │ Layer2: Logger                          │ │ ← 全局日志记录
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ Layer3: CORS                        │ │ │ ← 跨域处理
│ │ │ ┌─────────────────────────────────┐ │ │ │
│ │ │ │ Layer4: Auth                    │ │ │ │ ← 认证
│ │ │ │ ┌─────────────────────────────┐ │ │ │ │
│ │ │ │ │ Handler                     │ │ │ │ │ ← 业务处理
│ │ │ │ └─────────────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

响应流向（从内向外）：逆向执行Next后的代码

分层架构设计

标准分层模式

r := gin.New()

// Layer 1: 全局异常捕获（最外层）
r.Use(RecoveryMiddleware())

// Layer 2: 全局日志（次外层）
r.Use(LoggerMiddleware())

// Layer 3: 跨域处理
r.Use(CORSMiddleware())

// Layer 4: 请求追踪
r.Use(TraceMiddleware())

// 路由分组
api := r.Group("/api")
{
    // Layer 5: 认证层
    auth := api.Group("/")
    auth.Use(AuthMiddleware())

    // Layer 6: 权限层
    admin := auth.Group("/admin")
    admin.Use(PermissionMiddleware())

    // 业务路由
    admin.GET("/users", getUsers)
    admin.POST("/users", createUser)
}

中间件嵌套实现

路由组嵌套

func setupRouter() *gin.Engine {
    r := gin.New()

    // 全局中间件
    r.Use(GlobalMiddleware())

    // API分组
    api := r.Group("/api")
    api.Use(APIMiddleware())

    // v1版本分组
    v1 := api.Group("/v1")
    v1.Use(V1Middleware())

    // 用户分组
    users := v1.Group("/users")
    users.Use(UserMiddleware())

    // 路由注册
    users.GET("/:id", getUser)

    return r
}

// 中间件链顺序：
// Global → API → V1 → User → getUser

中间件组合器

// 组合多个中间件
func Chain(handlers ...gin.HandlerFunc) gin.HandlerFunc {
    return func(c *gin.Context) {
        for _, h := range handlers {
            h(c)
            if c.IsAborted() {
                return
            }
        }
        c.Next()
    }
}

// 使用示例
r.GET("/protected",
    Chain(
        AuthMiddleware(),
        PermissionMiddleware("admin"),
        RateLimitMiddleware(100),
    ),
    handler,
)

分层职责划分

条件中间件

按路径条件执行

func ConditionalMiddleware(condition func(*gin.Context) bool, handler gin.HandlerFunc) gin.HandlerFunc {
    return func(c *gin.Context) {
        if condition(c) {
            handler(c)
        } else {
            c.Next()
        }
    }
}

// 使用示例：仅API路径需要认证
r.Use(ConditionalMiddleware(
    func(c *gin.Context) bool {
        return strings.HasPrefix(c.Request.URL.Path, "/api/")
    },
    AuthMiddleware(),
))

按方法条件执行

func MethodMiddleware(methods []string, handler gin.HandlerFunc) gin.HandlerFunc {
    return func(c *gin.Context) {
        for _, m := range methods {
            if c.Request.Method == m {
                handler(c)
                return
            }
        }
        c.Next()
    }
}

// 仅POST和PUT需要验证
r.Use(MethodMiddleware(
    []string{"POST", "PUT"},
    ValidateMiddleware(),
))

中间件继承与隔离

继承模式

// 子路由组继承父路由组中间件
api := r.Group("/api", APIMiddleware())  // 父中间件
users := api.Group("/users", UserMiddleware())  // 子继承父+添加
// users路由执行：APIMiddleware → UserMiddleware → handler

隔离模式

// 创建不继承父中间件的独立路由组
r := gin.New()
r.Use(GlobalMiddleware())  // 全局

// 独立路由组（不继承全局）
standalone := gin.New()
standalone.GET("/health", healthCheck)

// 挂载独立路由组
r.Any("/health/*action", gin.WrapH(standalone))

分层最佳实践

执行顺序原则

// 正确顺序：从外到内，优先级递减
r.Use(Recovery())     // 1. 最外层：捕获所有panic
r.Use(Logger())       // 2. 日志记录
r.Use(CORS())         // 3. 跨域处理
r.Use(Auth())         // 4. 认证检查
r.Use(Permission())   // 5. 权限检查
r.Use(Validate())     // 6. 数据验证

避免顺序错误

// 错误示例：认证在日志前
r.Use(Auth())      // 先执行认证
r.Use(Logger())    // 后执行日志
// 问题：认证失败时无法记录日志

// 正确示例：日志在最外层
r.Use(Logger())    // 先记录
r.Use(Auth())      // 后认证

注意：Recovery必须在最外层，确保捕获所有异常。

要点总结

• 洋葱模型：请求从外向内，响应从内向外
• 分层设计按职责划分：基础→安全→追踪→认证→权限→业务
• 路由组嵌套实现中间件继承
• 条件中间件按路径或方法选择性执行
• Recovery必须在最外层，日志次之