4. 中间件模式：Go HTTP 中间件原理与权限挂载

中间件（Middleware）是 Go Web 框架中实现横切关注点（Cross-Cutting Concerns）的核心模式。在权限验证场景下，中间件允许你在请求进入业务处理器之前或之后，统一执行身份校验、Token 解析、角色判定等逻辑，而无需在每个业务方法中重复编写验证代码。

4.1 Go HTTP 中间件原理

Go 标准库 net/http 的中间件本质是一个函数类型，它接收一个 http.Handler 并返回一个新的 http.Handler。这种模式被称为“装饰器模式”或“洋葱模型”。

中间件的执行顺序遵循“先进后出”原则：请求从外层中间件向内层传递，响应从内层向外层返回。这种模型非常适合权限验证——在请求到达业务逻辑前完成校验，在响应返回时记录审计日志。

4.2 Gin / Echo / Chi 框架中的中间件实现

三大主流框架对中间件的实现各有特色，但核心思想一致：通过链式调用或注册表管理中间件序列。下表对比了它们在中间件注册、上下文传递和终止机制上的差异。

4.2.1 Gin 框架中间件示例

// 权限中间件定义
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            return
        }
        // 解析 Token，提取用户信息
        claims, err := parseToken(token)
        if err != nil {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "invalid token"})
            return
        }
        // 将用户信息注入上下文
        c.Set("user_id", claims.UserID)
        c.Set("role", claims.Role)
        c.Next() // 继续执行后续中间件和处理器
    }
}

// 路由组挂载
r := gin.Default()
adminGroup := r.Group("/api/admin")
adminGroup.Use(AuthMiddleware(), RoleMiddleware("admin"))
{
    adminGroup.GET("/users", listUsers)
    adminGroup.POST("/settings", updateSettings)
}

4.2.2 Echo 框架中间件示例

// 权限中间件定义
func AuthMiddleware() echo.MiddlewareFunc {
    return func(next echo.HandlerFunc) echo.HandlerFunc {
        return func(c echo.Context) error {
            token := c.Request().Header.Get("Authorization")
            if token == "" {
                return echo.NewHTTPError(http.StatusUnauthorized, "missing token")
            }
            claims, err := parseToken(token)
            if err != nil {
                return echo.NewHTTPError(http.StatusForbidden, "invalid token")
            }
            c.Set("user_id", claims.UserID)
            c.Set("role", claims.Role)
            return next(c) // 继续执行
        }
    }
}

// 路由组挂载
e := echo.New()
apiGroup := e.Group("/api/v1")
apiGroup.Use(AuthMiddleware())
{
    apiGroup.GET("/profile", getProfile)
    apiGroup.PUT("/profile", updateProfile)
}

4.2.3 Chi 框架中间件示例

// 权限中间件定义（兼容标准库）
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, "missing token", http.StatusUnauthorized)
            return
        }
        claims, err := parseToken(token)
        if err != nil {
            http.Error(w, "invalid token", http.StatusForbidden)
            return
        }
        // 使用 context 传递用户信息
        ctx := context.WithValue(r.Context(), "user_id", claims.UserID)
        ctx = context.WithValue(ctx, "role", claims.Role)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 路由组挂载
r := chi.NewRouter()
r.Route("/api/secure", func(r chi.Router) {
    r.Use(AuthMiddleware)
    r.Get("/data", getSecureData)
    r.Post("/data", createSecureData)
})

4.3 权限中间件的挂载点

权限中间件的挂载位置直接影响系统的安全粒度和性能。根据业务需求，可以选择不同的挂载策略：

• 全局挂载：所有路由都经过权限验证，适用于全站统一认证的场景。缺点是无法灵活排除公开接口。
• 路由组挂载：按模块或版本分组，不同组使用不同的权限策略。这是最常用的方式，兼顾灵活性和安全性。
• 路由级挂载：为单个路由单独指定中间件，适用于特殊权限要求的接口。
• 条件挂载：在中间件内部根据请求路径、方法或头部动态决定是否执行验证。

4.4 权限中间件的挂载策略对比

4.5 中间件中的上下文传递与终止

权限中间件的核心职责有两个：传递认证信息和在验证失败时终止请求。不同框架的实现方式略有差异：

• Gin：使用 c.Set(key, value) 注入上下文，c.Abort() 终止后续中间件执行。
• Echo：使用 c.Set(key, value) 注入上下文，返回 echo.HTTPError 终止链式调用。
• Chi：使用标准库 context.WithValue 注入，通过 http.Error 或 return 终止。