4. Gin框架入门：路由、中间件、请求校验与响应格式

Gin 是 Go 语言生态中最流行的 Web 框架之一，以高性能、低内存占用和简洁的 API 设计著称。本章将围绕 Gin 的核心能力展开：路由注册与分组、中间件链式处理、请求参数绑定与校验，以及灵活的响应格式输出。这些能力是构建业务回放与权限验证系统的基础设施。

4.1 路由与路由分组

Gin 的路由基于 Radix Tree（基数树）实现，支持精确匹配、参数匹配和通配符。路由分组用于将具有相同前缀或中间件的路由组织在一起，提升代码可维护性。

// 路由分组示例
r := gin.Default()

// 公开路由组
public := r.Group("/api/v1")
{
    public.POST("/login", authHandler.Login)
    public.POST("/register", authHandler.Register)
}

// 受保护路由组（需要认证中间件）
protected := r.Group("/api/v1")
protected.Use(middleware.JWTAuth())
{
    protected.GET("/users", userHandler.List)
    protected.GET("/users/:id", userHandler.GetByID)
    protected.PUT("/users/:id", userHandler.Update)
}

4.2 中间件机制

Gin 的中间件是处理 HTTP 请求/响应链的函数，支持在请求到达处理函数之前或之后执行逻辑。中间件可以访问 gin.Context，通过 c.Next() 调用后续处理链，通过 c.Abort() 中断请求。

// 自定义日志中间件
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        path := c.Request.URL.Path

        // 请求前
        c.Next()

        // 请求后
        latency := time.Since(start)
        status := c.Writer.Status()
        log.Printf("[%d] %s %v", status, path, latency)
    }
}

// 使用中间件
r.Use(LoggerMiddleware())

4.3 请求参数绑定与校验

Gin 支持将请求参数（Query、Form、JSON、URI）自动绑定到结构体，并集成 go-playground/validator 进行字段校验。绑定标签使用 form、json、uri 等，校验标签使用 binding。

// 请求参数结构体
type CreateUserRequest struct {
    Username string `json:"username" binding:"required,min=3,max=32"`
    Email    string `json:"email" binding:"required,email"`
    Age      int    `json:"age" binding:"gte=0,lte=150"`
    Role     string `json:"role" binding:"required,oneof=admin user viewer"`
}

// 绑定与校验
func CreateUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        // 校验失败，返回错误信息
        c.JSON(http.StatusBadRequest, gin.H{
            "error": err.Error(),
        })
        return
    }
    // 业务处理...
    c.JSON(http.StatusOK, gin.H{"message": "用户创建成功"})
}

4.4 响应格式：JSON 与 XML

Gin 内置对 JSON 和 XML 响应的支持，通过 c.JSON() 和 c.XML() 方法即可输出。对于需要根据客户端 Accept 头自动选择格式的场景，可以使用 c.Negotiate()。

// JSON 响应
c.JSON(http.StatusOK, gin.H{
    "code":    0,
    "message": "success",
    "data":    user,
})

// XML 响应
c.XML(http.StatusOK, gin.H{
    "code":    0,
    "message": "success",
    "data":    user,
})

// 内容协商（根据 Accept 头自动选择）
c.Negotiate(http.StatusOK, gin.Negotiate{
    Offered:  []string{gin.MIMEJSON, gin.MIMEXML},
    Data:     gin.H{"code": 0, "data": user},
})

4.5 统一响应封装

在实际项目中，建议封装统一的响应结构，避免每个处理函数重复编写 gin.H。统一响应有助于前端解析和后端维护。

// 统一响应结构体
type Response struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

// 成功响应
func Success(c *gin.Context, data interface{}) {
    c.JSON(http.StatusOK, Response{
        Code:    0,
        Message: "success",
        Data:    data,
    })
}

// 错误响应
func Error(c *gin.Context, httpStatus int, code int, message string) {
    c.JSON(httpStatus, Response{
        Code:    code,
        Message: message,
    })
}

// 使用示例
func GetUser(c *gin.Context) {
    user, err := userService.GetByID(c.Param("id"))
    if err != nil {
        Error(c, http.StatusNotFound, 1001, "用户不存在")
        return
    }
    Success(c, user)
}

4.6 本章小结

• Gin 路由支持精确匹配、路径参数和通配符，路由分组是组织代码的核心手段。
• 中间件通过 c.Next() 和 c.Abort() 控制请求链，适用于日志、鉴权、限流等横切关注点。
• 参数绑定使用 ShouldBind* 系列方法，校验通过 binding 标签声明规则。
• 响应格式支持 JSON、XML 和内容协商，建议封装统一响应结构体。
• 本章内容为后续实现业务回放与权限验证提供了完整的 Web 层基础设施。