3. 路由基础：Gin的路由引擎、HTTP方法绑定与处理函数签名

Gin 框架的核心是高性能的路由引擎，它基于 Radix Tree（基数树） 实现，支持精确匹配、参数匹配和通配符匹配。本章将深入剖析路由引擎的初始化、HTTP 方法绑定规范以及处理函数的签名约定，为后续的路由分组与中间件设计奠定基础。

3.1 路由引擎的创建与配置

Gin 的路由引擎通过 gin.New() 或 gin.Default() 创建。两者的区别在于是否预置了中间件：

创建方式	预置中间件	适用场景
gin.New()	无	需要完全自定义中间件栈
gin.Default()	Logger + Recovery	快速开发、生产环境基础配置

// 创建路由引擎
router := gin.New()

// 手动挂载中间件
router.Use(gin.Logger())
router.Use(gin.Recovery())

// 或者直接使用默认引擎
// router := gin.Default()

3.2 HTTP 方法绑定

Gin 为每个标准 HTTP 方法提供了独立的绑定方法，方法签名高度一致。以下是核心绑定方法及其对应关系：

HTTP 方法	Gin 绑定方法	典型用途
GET	router.GET(path, handler)	查询资源
POST	router.POST(path, handler)	创建资源
PUT	router.PUT(path, handler)	全量更新资源
DELETE	router.DELETE(path, handler)	删除资源
PATCH	router.PATCH(path, handler)	部分更新资源
HEAD	router.HEAD(path, handler)	获取响应头
OPTIONS	router.OPTIONS(path, handler)	预检请求

// 标准 RESTful 路由绑定示例
router.GET("/users", listUsers)
router.POST("/users", createUser)
router.PUT("/users/:id", updateUser)
router.DELETE("/users/:id", deleteUser)

3.3 处理函数签名

Gin 的处理函数必须遵循固定的签名格式：

func handlerFunction(c *gin.Context) {
    // 处理逻辑
}

其中 *gin.Context 是请求上下文的指针，它封装了请求和响应的全部操作能力。下表列出了 Context 的核心方法分类：

类别	常用方法	说明
请求参数	c.Param(), c.Query(), c.PostForm()	获取路径参数、查询参数、表单参数
请求体	c.ShouldBindJSON(), c.ShouldBindXML()	自动解析并绑定请求体到结构体
响应输出	c.JSON(), c.String(), c.HTML()	返回 JSON、字符串或 HTML 响应
状态码	c.Status(), c.AbortWithStatus()	设置 HTTP 状态码或中断请求链
中间件	c.Next(), c.Set(), c.Get()	控制中间件执行流程与上下文传递

// 完整处理函数示例
func getUserByID(c *gin.Context) {
    // 1. 获取路径参数
    id := c.Param("id")

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

    // 3. 业务逻辑（省略）
    user := fetchUserFromDB(id)

    // 4. 返回 JSON 响应
    c.JSON(http.StatusOK, gin.H{
        "id":   id,
        "page": page,
        "user": user,
    })
}

3.4 路由引擎与请求处理流程

下图展示了 Gin 路由引擎从请求接收到响应返回的完整流程，重点突出路由匹配与处理函数调用的边界：

3.5 路由分组与作用域预览

Gin 的路由分组（Group）本质上是创建了一个路径前缀，并允许为该组统一绑定中间件。理解路由引擎的底层机制后，分组设计将更加清晰：

// 路由分组示例
v1 := router.Group("/api/v1")
{
    v1.GET("/users", listUsers)
    v1.POST("/users", createUser)
}

// 分组 + 中间件
admin := router.Group("/admin", AuthMiddleware())
{
    admin.GET("/dashboard", dashboardHandler)
    admin.POST("/settings", updateSettings)
}

3.6 本章小结

• 路由引擎： 使用 gin.New() 或 gin.Default() 创建，底层基于 Radix Tree 实现高效匹配。
• HTTP 方法绑定： 每个标准方法都有独立的绑定方法，路径参数使用 :param 语法。
• 处理函数签名： 固定为 func(c *gin.Context)，Context 是请求与响应的统一操作入口。
• 执行顺序： 全局中间件 → 路由匹配 → 处理函数 → 响应返回，这一顺序是中间件作用域设计的基础。