3. 路由基础：GET/POST/PUT/DELETE路由注册、路由分组(Group)、路由参数(:param与*param)

Gin 框架的路由系统是其核心能力之一，它基于 Radix Tree（基数树） 实现，提供了高效、灵活且语义清晰的 HTTP 方法绑定与路径匹配机制。本章将深入讲解 Gin 路由的四大基础操作：方法路由注册、路由分组、路径参数（:param）与通配符参数（*param）。

3.1 HTTP 方法路由注册

Gin 为每个标准 HTTP 方法提供了独立的注册函数，开发者可以直接在路由引擎上调用对应方法，将处理函数绑定到指定路径。这是构建 RESTful API 的基石。

package main

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

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

    // GET 路由
    router.GET("/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "获取用户列表"})
    })

    // POST 路由
    router.POST("/users", func(c *gin.Context) {
        c.JSON(http.StatusCreated, gin.H{"message": "创建用户成功"})
    })

    // PUT 路由
    router.PUT("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"message": "更新用户 " + id})
    })

    // DELETE 路由
    router.DELETE("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"message": "删除用户 " + id})
    })

    router.Run(":8080")
}

3.2 路由分组 (Group)

路由分组是 Gin 提供的一种强大的组织机制，允许开发者将具有相同路径前缀或中间件逻辑的路由聚合在一起。分组可以嵌套，形成清晰的层级结构，极大提升代码的可维护性。

分组的主要用途包括：

• 统一路径前缀： 例如将所有 API 接口放在 /api/v1 下。
• 共享中间件： 为分组内的所有路由统一应用认证、日志、限流等中间件。
• 模块化拆分： 按业务模块（如用户、订单、商品）划分路由组，便于团队协作。

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

    // 顶层分组：API v1
    v1 := router.Group("/api/v1")
    {
        // 用户模块分组
        users := v1.Group("/users")
        {
            users.GET("/", listUsers)
            users.POST("/", createUser)
            users.GET("/:id", getUserByID)
            users.PUT("/:id", updateUser)
            users.DELETE("/:id", deleteUser)
        }

        // 订单模块分组
        orders := v1.Group("/orders")
        {
            orders.GET("/", listOrders)
            orders.POST("/", createOrder)
            orders.GET("/:orderId", getOrderByID)
        }
    }

    // 另一顶层分组：管理后台
    admin := router.Group("/admin", AuthMiddleware())
    {
        admin.GET("/dashboard", adminDashboard)
        admin.GET("/users", adminListUsers)
    }

    router.Run(":8080")
}

3.3 路由参数：:param 与 *param

Gin 支持两种动态路径参数：命名参数（:param） 和 通配符参数（*param）。它们允许路由匹配可变路径段，是实现 RESTful 资源标识的核心机制。

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

    // 命名参数 :id
    router.GET("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.String(http.StatusOK, "用户 ID: %s", id)
    })

    // 多个命名参数
    router.GET("/posts/:year/:month/:day", func(c *gin.Context) {
        year  := c.Param("year")
        month := c.Param("month")
        day   := c.Param("day")
        c.String(http.StatusOK, "日期: %s-%s-%s", year, month, day)
    })

    // 通配符参数 *path
    router.GET("/static/*filepath", func(c *gin.Context) {
        filepath := c.Param("filepath")
        c.String(http.StatusOK, "请求的静态文件路径: %s", filepath)
    })

    router.Run(":8080")
}

3.4 路由匹配优先级与冲突

Gin 的路由匹配遵循 最长前缀匹配 原则，同时静态路径的优先级高于动态参数路径。理解这一规则有助于避免路由冲突。

• 静态路径优先： /users/new 的优先级高于 /users/:id。当请求 /users/new 时，会匹配到静态路由，而不会将 new 作为 :id 的参数值。
• 冲突检测： Gin 在路由注册时会自动检测冲突。例如，同时注册 /users/:id 和 /users/:name 会引发 panic，因为两者在相同位置使用了不同的参数名。
• 通配符独占： 通配符参数 *param 只能出现在路径末尾，且一个路径中只能有一个通配符参数。

3.5 路由架构总览

下面的 SVG 图展示了 Gin 路由系统的整体架构，从 HTTP 请求进入，经过路由分组、路径匹配、参数提取，最终到达处理函数的完整链路。

3.6 路由分组与参数组合实战

在实际项目中，路由分组和参数通常组合使用，形成清晰且可扩展的 API 结构。下面的 SVG 图展示了一个典型的电商后台路由设计。

3.7 路由注册最佳实践清单

在 Gin 项目中，遵循以下最佳实践可以显著提升路由的可维护性和性能：