3. 路由与中间件：使用Gin框架实现路由分组、中间件机制（日志、鉴权）

在构建可维护的 Web 服务时，路由的组织方式与中间件的复用能力直接决定了代码的整洁度与安全性。Gin 框架提供了轻量级的路由分组机制和灵活的中间件链，使得开发者能够以极低的成本实现日志记录、身份鉴权、请求限流等横切关注点。本章将深入讲解路由分组的实践模式，并手把手实现日志与鉴权中间件。

3.1 路由分组：模块化与版本控制

路由分组（Router Group）是 Gin 中用于将具有相同前缀或中间件的一组路由进行逻辑归类的核心机制。它天然支持 API 版本控制（如 /api/v1）和业务模块划分（如 /admin、/user）。

3.1.1 基础分组语法

通过 gin.RouterGroup 的 Group() 方法创建子分组，并链式调用 HTTP 方法注册路由。

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    // 创建 /api/v1 分组
    v1 := r.Group("/api/v1")
    {
        v1.GET("/users", listUsers)
        v1.POST("/users", createUser)
        v1.GET("/users/:id", getUserByID)
    }

    // 创建 /admin 分组
    admin := r.Group("/admin")
    {
        admin.GET("/dashboard", adminDashboard)
        admin.POST("/settings", updateSettings)
    }

    r.Run(":8080")
}

func listUsers(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"message": "list users"})
}
// ... 其他处理函数省略

3.1.2 嵌套分组与路径拼接

分组支持无限嵌套，内部路由的完整路径由所有外层分组的路径前缀拼接而成。

3.2 中间件机制：请求处理管道

中间件（Middleware）是 Gin 中处理请求/响应周期的钩子函数。它可以在请求到达路由处理函数之前执行预处理（如日志、鉴权、限流），也可以在响应返回客户端之前执行后处理（如统一错误格式、添加响应头）。

Gin 的中间件本质上是 gin.HandlerFunc，通过 c.Next() 调用后续的处理函数，形成一条处理链。

3.2.1 日志中间件实现

一个生产级别的日志中间件应记录请求方法、路径、状态码、耗时和客户端 IP。

// LoggerMiddleware 记录请求日志
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求开始时间
        start := time.Now()
        path := c.Request.URL.Path
        method := c.Request.Method

        // 处理请求
        c.Next()

        // 请求结束后计算耗时
        latency := time.Since(start)
        statusCode := c.Writer.Status()
        clientIP := c.ClientIP()

        // 输出日志（实际项目中建议使用结构化日志库如 zap）
        log.Printf("[GIN] %s | %3d | %13v | %15s | %s",
            method,
            statusCode,
            latency,
            clientIP,
            path,
        )
    }
}

3.2.2 鉴权中间件实现

鉴权中间件通常从请求头中提取 Token，验证其有效性后，将用户信息注入上下文，供后续处理函数使用。

// AuthMiddleware 简单的 Bearer Token 鉴权
func AuthMiddleware(validToken string) gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
                "error": "缺少 Authorization 头",
            })
            return
        }

        // 期望格式: "Bearer "
        parts := strings.SplitN(token, " ", 2)
        if len(parts) != 2 || parts[0] != "Bearer" || parts[1] != validToken {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
                "error": "无效的 Token",
            })
            return
        }

        // 将用户信息注入上下文
        c.Set("user_id", "u-1001")
        c.Set("role", "admin")

        // 继续处理请求
        c.Next()
    }
}

3.3 路由分组与中间件组合实践

将日志中间件应用于全局，将鉴权中间件仅挂载到需要保护的 /admin 分组上，实现最小权限原则。

func main() {
    r := gin.New() // 使用 New() 避免默认的 Logger 和 Recovery 中间件

    // 全局中间件：所有路由都记录日志
    r.Use(LoggerMiddleware())
    r.Use(gin.Recovery()) // 恢复 panic

    // 公开 API，无需鉴权
    public := r.Group("/api/v1")
    {
        public.POST("/login", loginHandler)
        public.GET("/products", listProducts)
    }

    // 管理后台，需要鉴权
    admin := r.Group("/admin")
    admin.Use(AuthMiddleware("my-secret-token-2024"))
    {
        admin.GET("/dashboard", adminDashboard)
        admin.POST("/settings", updateSettings)
        admin.GET("/users", listAllUsers)
    }

    r.Run(":8080")
}

3.4 中间件执行流程可视化

下图展示了 Gin 中间件链的执行顺序，以及 c.Next() 在其中的关键作用。

3.5 中间件注册方式对比

3.6 最佳实践与避坑指南

• 中间件顺序敏感： 将 Recovery 中间件放在最外层，确保 panic 能被捕获；将日志中间件放在靠前位置，以便记录所有请求（包括被鉴权拒绝的请求）。
• 避免在中间件中修改请求体： 请求体是流式读取的，中间件中读取后需重新设置 c.Request.Body，否则后续处理函数无法读取。
• 使用 c.Set() / c.Get() 传递上下文： 不要在中间件中使用全局变量传递用户信息，应通过 Gin 的上下文机制保证并发安全。
• 中间件复用： 将通用中间件（如日志、鉴权）抽取为独立函数，通过闭包传递配置参数，提高复用性。