核心概念

本章深入讲解 Gin 中的核心类型和运作机制，理解这些是正确使用框架的基础。

gin.Engine — 路由引擎

gin.Engine 是 Gin 框架的核心，实现了 http.Handler 接口，负责：

• 路由注册与匹配（基于 radix tree）
• 中间件链管理
• 请求生命周期调度
• 渲染与序列化

// Engine 实现了 http.Handler 接口
var _ http.Handler = (*gin.Engine)(nil)

// 可以直接传给标准库
http.ListenAndServe(":8080", engine)

🔬 深入原理：Gin 使用 httprouter 的 radix tree 实现路由匹配，时间复杂度 O(log n)，比传统线性遍历的 O(n) 快数倍。这只在路由数量极大时才有明显感知。

gin.Context — 请求上下文

gin.Context 是 Gin 中最重要的类型，贯穿每个请求的整个生命周期。它封装了：

func handler(c *gin.Context) {
    // 请求信息
    method := c.Request.Method
    path := c.Request.URL.Path
    clientIP := c.ClientIP()

    // 路径参数
    id := c.Param("id")

    // 查询参数
    page := c.DefaultQuery("page", "1")

    // 上下文数据传递
    c.Set("user_id", 123)

    // 响应
    c.JSON(200, gin.H{"method": method, "path": path})
}

🚨 陷阱：gin.Context 使用 sync.Pool 对象池复用，请求结束后会被回收。禁止在 goroutine 中直接使用原始 context，必须先用 c.Copy() 创建副本。详见 10-上下文与并发。

gin.HandlerFunc — 处理函数

type HandlerFunc func(*Context)

所有路由处理函数和中间件都遵循此签名。关键区别在于中间件会调用 c.Next() 将控制权传递给下一个处理函数。

gin.H — 快捷 map

type H map[string]interface{}
// 等价于 map[string]any

用于构建 JSON 响应的快捷类型：

c.JSON(200, gin.H{
    "status":  "ok",
    "message": "hello",
})
// 等价于
c.JSON(200, map[string]interface{}{
    "status":  "ok",
    "message": "hello",
})

Radix Tree 路由原理

Gin 的路由基于 radix tree（基数树/压缩前缀树），这是一种优化的 trie 树结构：

/           (根)
├── ping
├── user/
│   ├── :id
│   └── :id/profile
└── api/
    ├── v1/
    │   └── users
    └── v2/
        └── users

特性：

• 公共前缀被合并为单一节点，节省内存
• 路由查找是 O(路径长度 × 常数)，而非 O(路由数量)
• 支持 :param（单段）和 *any（通配）两种动态参数
• 路由冲突（如同时注册 /user/new 和 /user/:id）在注册时触发 panic

🔬 深入原理：与标准库 http.ServeMux 不同，Gin 在一个请求中匹配到第一个路由后即停止。没有"最长匹配"概念——如果两个路由 /user/:id 和 /user/profile 同时注册，Gin 会根据 radix tree 的遍历顺序命中其中一个，不能保证 /user/profile 被优先匹配。实践中应避免这种冲突。

中间件执行模型

Gin 的中间件链是一个洋葱模型：

请求 → [Logger 前] → [Auth 前] → 处理函数 → [Auth 后] → [Logger 后] → 响应

        ┌──────────────────────────┐
        │     Logger 中间件         │
        │  ┌────────────────────┐   │
        │  │  Auth 中间件        │   │
        │  │ ┌────────────────┐ │   │
        │  │ │  处理函数       │ │   │
        │  │ └────────────────┘ │   │
        │  └────────────────────┘   │
        └──────────────────────────┘

• c.Next() 之前的代码：请求进入阶段
• c.Next() 之后的代码：响应离开阶段
• c.Abort()：跳过后续所有处理函数，直接返回

💡 理解这个模型对编写自定义中间件至关重要。如果你需要在处理完成后记录日志、统计耗时，就把代码放在 c.Next() 之后。