4. Gin框架快速入门：路由定义、请求参数绑定（ShouldBind）、响应格式（JSON/XML）、中间件注册

Gin 是 Go 语言生态中最流行的 Web 框架之一，以高性能、低内存占用和简洁的 API 设计著称。在业务接口落地过程中，Gin 提供了从路由注册到参数校验、响应输出、中间件编排的完整链路。本章聚焦 Gin 框架的四个核心操作：路由定义、请求参数绑定（ShouldBind）、响应格式（JSON/XML）、中间件注册，为后续安全防护与 SQL 注入防范打下基础。

4.1 路由定义：从基础到分组

Gin 的路由基于 Radix Tree（基数树）实现，支持精确匹配、参数占位符、通配符和重定向。路由定义是业务接口的入口，直接影响接口的可维护性与安全性。

// 基础路由示例
r := gin.Default()

// 精确匹配
r.GET("/health", func(c *gin.Context) {
    c.JSON(200, gin.H{"status": "ok"})
})

// 参数占位符
r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.String(200, "User ID: %s", id)
})

// 路由分组 —— 业务接口常用模式
api := r.Group("/api/v1")
{
    api.GET("/users", listUsers)
    api.POST("/users", createUser)
    api.GET("/users/:id", getUserByID)
}

4.2 请求参数绑定：ShouldBind 与数据校验

Gin 的 ShouldBind 系列方法将请求体（JSON、XML、Form）自动解析到结构体，并支持内置校验标签（binding:"required"）。相比 Bind 系列，ShouldBind 在绑定失败时返回错误但不中断请求，适合需要自定义错误响应的场景。

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"`
}

func createUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        // 自定义错误响应，不暴露内部校验细节
        c.JSON(400, gin.H{
            "code":    40001,
            "message": "参数校验失败",
            "detail":  err.Error(), // 开发阶段可保留，生产环境建议脱敏
        })
        return
    }
    // 业务逻辑：参数已安全绑定到结构体
    c.JSON(201, gin.H{"user_id": generateID()})
}

4.3 响应格式：JSON 与 XML 输出

Gin 原生支持 c.JSON、c.XML、c.String、c.HTML 等响应方式。在 RESTful 业务接口中，JSON 是主流格式；XML 常用于遗留系统或特定行业协议。

// JSON 响应 —— 标准 RESTful 格式
c.JSON(200, gin.H{
    "code":    0,
    "message": "success",
    "data":    user,
})

// XML 响应 —— 适用于 SOAP 或企业集成
c.XML(200, gin.H{
    "code":    0,
    "message": "success",
})

// 自定义结构体响应（推荐）
type ApiResponse struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

c.JSON(200, ApiResponse{
    Code:    0,
    Message: "success",
    Data:    userList,
})

4.4 中间件注册：全局与局部拦截

中间件是 Gin 安全防护的核心机制。通过中间件，可以在请求进入业务处理前统一执行日志记录、身份认证、请求限流、SQL 注入检测等逻辑。Gin 支持全局中间件、分组中间件和单路由中间件三种注册方式。

// 1. 全局中间件 —— 所有路由生效
r := gin.Default() // 默认包含 Logger 和 Recovery
r.Use(gin.Logger())   // 显式添加日志中间件
r.Use(gin.Recovery()) // 显式添加异常恢复中间件

// 2. 分组中间件 —— 仅对 /api/v1 分组生效
api := r.Group("/api/v1")
api.Use(AuthMiddleware()) // 认证中间件
{
    api.GET("/users", listUsers)
    api.POST("/users", createUser)
}

// 3. 单路由中间件 —— 仅对特定路由生效
r.GET("/admin/dashboard", AdminOnlyMiddleware(), dashboardHandler)

// 自定义中间件示例：请求日志与安全检测
func SecurityMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求前：记录原始请求信息
        start := time.Now()
        ip := c.ClientIP()
        path := c.Request.URL.Path

        // 安全检测：检查请求体中是否包含 SQL 注入特征
        if containsSQLInjection(c.Request) {
            c.AbortWithStatusJSON(403, gin.H{
                "code":    40301,
                "message": "请求被安全策略拦截",
            })
            return
        }

        // 继续执行后续处理
        c.Next()

        // 请求后：记录响应耗时
        latency := time.Since(start)
        log.Printf("[%s] %s %s %v", ip, c.Request.Method, path, latency)
    }
}

4.5 综合示例：安全路由注册模板

将路由、参数绑定、响应格式与中间件整合为一个安全的路由注册模板，是业务接口落地的标准实践。

func SetupRouter() *gin.Engine {
    r := gin.New() // 不包含默认中间件，手动注册

    // 全局中间件：日志 + 异常恢复 + 安全检测
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    r.Use(SecurityMiddleware())

    // 健康检查 —— 无需认证
    r.GET("/health", healthHandler)

    // API v1 分组 —— 需要认证
    v1 := r.Group("/api/v1")
    v1.Use(AuthMiddleware())
    {
        v1.GET("/users", listUsers)
        v1.POST("/users", createUser)
        v1.GET("/users/:id", getUserByID)
        v1.PUT("/users/:id", updateUser)
        v1.DELETE("/users/:id", deleteUser)
    }

    // API v2 分组 —— 不同认证策略
    v2 := r.Group("/api/v2")
    v2.Use(APITokenMiddleware())
    {
        v2.GET("/products", listProducts)
        v2.POST("/products", createProduct)
    }

    return r
}

func main() {
    r := SetupRouter()
    r.Run(":8080") // 监听 8080 端口
}