3、路由与分组：基础路由、参数路由、通配符路由、路由分组与嵌套、路由优先级

路由，说白了就是 Web 框架的「交通指挥员」。你发一个请求过来，它得知道该交给哪个函数去处理。我见过不少新手项目，路由写得乱七八糟，最后维护起来简直想哭。今天咱们就把路由这块彻底聊透。

3.1 基础路由：最朴素的请求分发

基础路由就是最简单的路径匹配。比如 /hello 就匹配 /hello，/user 就匹配 /user。没什么花哨的，但它是所有路由的基石。

我个人习惯在项目初期先用基础路由把核心接口搭起来。举个例子：

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

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })

    r.POST("/login", loginHandler)
    r.PUT("/user", updateUserHandler)
    r.DELETE("/user", deleteUserHandler)

    r.Run()
}

你看，每个 HTTP 方法对应一个路由注册函数。GET、POST、PUT、DELETE，一一对应。这里有个小细节：同一个路径可以注册不同的方法，它们互不干扰。

我的习惯：基础路由的路径命名尽量用名词复数形式，比如 /users、/orders。别用动词，因为 HTTP 方法本身就表达了动作。

3.2 参数路由：从 URL 里拿数据

实际项目中，我们经常需要从 URL 里提取动态数据。比如获取某个用户的详情：/user/123，这里的 123 是用户 ID。用参数路由就对了。

r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")
    // 用 id 去数据库查用户
    c.JSON(200, gin.H{"user_id": id})
})

:id 就是一个路径参数。你访问 /user/42，c.Param("id") 就能拿到 "42"。嗯，这里要注意：参数拿到的永远是字符串，需要自己转成 int 或其他类型。

我在项目中遇到过一个问题：有人把参数路由和查询参数搞混了。查询参数是 /user?id=123，用 c.Query("id") 获取。两者用法不同，别弄混了。

我曾经踩过的坑：参数路由的冒号后面不要加空格。写成 /user/: id 会直接报错。还有，参数名不要用中文，虽然框架可能支持，但容易出编码问题。

3.3 通配符路由：匹配一切剩余路径

通配符路由用 * 表示，它会匹配路径中剩下的所有内容。比如 /static/*filepath，你访问 /static/js/app.js，filepath 的值就是 js/app.js。

这玩意儿最适合做静态文件服务：

r.GET("/static/*filepath", func(c *gin.Context) {
    filePath := c.Param("filepath")
    // 拼接实际文件路径，返回文件
    c.File("./public/" + filePath)
})

你想想看，如果没有通配符，你得为每个静态文件写一个路由，那得写到猴年马月去。通配符路由就是用来处理这种「不确定路径长度」的场景的。

但要注意：通配符只能放在路径末尾。你不能写 /static/*filepath/version，这样框架会报错。为什么？因为通配符匹配的是剩余所有路径，后面不能再跟其他路径段了。

3.4 路由分组与嵌套：让代码结构清晰起来

项目大了以后，路由会越来越多。几十个路由堆在一起，看着就头疼。这时候就需要路由分组了。

路由分组，说白了就是把功能相关的路由放在一个组里。比如所有用户相关的接口放在 /api/v1/user 下面：

v1 := r.Group("/api/v1")
{
    user := v1.Group("/user")
    {
        user.GET("/:id", getUser)
        user.POST("", createUser)
        user.PUT("/:id", updateUser)
        user.DELETE("/:id", deleteUser)
    }

    order := v1.Group("/order")
    {
        order.GET("/:id", getOrder)
        order.POST("", createOrder)
    }
}

你看，这样一分组，代码结构就清晰多了。每个组只关心自己的路由，互不干扰。而且分组可以嵌套，就像上面那样，/api/v1/user/:id 就是嵌套分组的结果。

我个人习惯：分组最多嵌套三层。超过三层，代码可读性就会下降。比如 /api/v1/admin/user/role/:id，这种路径虽然能工作，但维护起来很痛苦。

分组的好处：
  • 路径前缀统一管理，改一处全改
  • 可以给分组统一加中间件（比如鉴权、日志）
  • 代码结构清晰，新人接手也看得懂

3.5 路由优先级：谁先匹配谁先上

路由优先级是个容易忽略但很重要的问题。当多个路由都能匹配同一个请求时，框架怎么选？

在 Gin 里，路由优先级遵循一个简单原则：越精确的匹配优先级越高。具体来说：

路由类型 示例 优先级
静态路由 /user/profile 最高
参数路由 /user/:id 中等
通配符路由 /user/*action 最低

举个例子，如果你同时注册了 /user/profile 和 /user/:id，访问 /user/profile 时，静态路由会优先匹配。因为 profile 是确定的字符串，比 :id 更精确。

我曾经在项目中遇到过一个问题：有人把 /user/:id 和 /user/profile 的顺序写反了，结果 /user/profile 一直匹配到参数路由，拿到 id = "profile"，然后去数据库查，自然查不到数据。嗯，这就是优先级没搞明白的后果。

避坑指南：虽然框架会自动处理优先级，但建议你写路由时，把静态路由写在参数路由前面。这样代码读起来更符合直觉，也方便其他人 review。

3.6 实战中的路由设计建议

聊了这么多理论，最后分享几个我在实战中总结的路由设计原则：

  1. 版本号放路径里：比如 /api/v1/、/api/v2/。这样接口升级时可以平滑过渡，老版本还能继续用。
  2. 资源用名词复数：/users、/orders、/products。别用 /getUser 这种带动词的命名。
  3. 嵌套不要太深：路径层级控制在 3-4 层以内。太深的路径不仅难读，而且性能也会受影响。
  4. 统一错误处理：给路由分组统一加一个 recovery 中间件，防止某个 handler 崩溃导致整个服务挂掉。

路由设计得好，后续的维护工作能省一半力气。我见过太多项目，前期图省事随便写路由，后期改一个接口路径要翻遍整个代码库。别学他们，从一开始就把路由规划好。

我的小技巧：在项目根目录建一个 router.go 文件，专门放路由注册代码。所有路由分组、中间件都在这里统一管理。这样其他人看代码时，打开这个文件就能了解整个项目的接口结构。

好了，路由这块就聊到这儿。下一章咱们聊聊中间件，那玩意儿才是真正让 Web 框架变得灵活的关键。到时候我会分享一些我在生产环境中用过的中间件模式，保证实用。

← 上一章 📖 返回目录 下一章 →