Gin 路由组

calendar Mar 10, 2025 · 2 min read · go gin

Gin 框架中的 RouterGroup（路由组） 是组织和管理路由的重要机制，它允许将一组具有相同前缀路径或共用中间件的路由逻辑性地分组，提高代码的可读性和可维护性。

RouterGroup 的核心作用

  1. 统一前缀路径
    为一组路由设置公共的 URL 前缀（例如 /api/v1）。
  2. 批量添加中间件
    为一组路由统一添加中间件（如认证、日志、权限检查）。
  3. 嵌套结构
    支持路由组的嵌套，形成层次化路由结构。

创建路由组

通过 Group() 方法创建路由组，语法如下：

1router := gin.Default()
2v1 := router.Group("/v1") // 创建以 /v1 为前缀的路由组
3admin := router.Group("/admin") // 另一个路由组

路由组的用法

1. 统一前缀路径

1api := router.Group("/api")
2{
3    api.GET("/users", listUsers)   // 实际路径: /api/users
4    api.POST("/users", createUser) // 实际路径: /api/users
5}

2. 批量添加中间件

1auth := router.Group("/auth")
2auth.Use(AuthMiddleware()) // 为该组所有路由添加认证中间件
3{
4    auth.GET("/profile", getProfile)
5    auth.POST("/logout", logout)
6}

3. 嵌套路由组

1v1 := router.Group("/v1")
2{
3    // 子路由组 /v1/admin
4    admin := v1.Group("/admin")
5    admin.Use(AdminCheck()) // 仅对 /v1/admin 下的路由生效
6    {
7        admin.GET("/stats", getStats) // 路径: /v1/admin/stats
8    }
9}

实际应用场景

  1. RESTful API 版本管理
    通过 /v1、/v2 路由组区分不同 API 版本。

  2. 权限分层
    公共路由、用户路由、管理员路由通过不同路由组隔离。

  3. 模块化开发
    将不同功能模块（如 /user、/order）的路由分组到不同文件中。

注意事项

  • 中间件作用范围
    路由组的中间件仅对组内路由生效，不会影响其他路由组。

  • 路径优先级
    Gin 的路由匹配是精确匹配，子路由组路径会继承父组前缀。

  • 代码组织
    可以将路由组的定义拆分到不同函数或文件中，例如：

    1func setupUserRoutes(r *gin.RouterGroup) {
2    r.GET("/", getUsers)
3    r.POST("/", createUser)
4}
5// 主函数中调用
6userGroup := router.Group("/users")
7setupUserRoutes(userGroup)

完整示例

 1package main
 2
 3import "github.com/gin-gonic/gin"
 4
 5func main() {
 6    router := gin.Default()
 7
 8    // 公共路由组（无中间件）
 9    public := router.Group("/public")
10    {
11        public.GET("/info", func(c *gin.Context) {
12            c.String(200, "Public Information")
13        })
14    }
15
16    // 私有路由组（需要认证）
17    private := router.Group("/private")
18    private.Use(AuthMiddleware())
19    {
20        private.GET("/profile", func(c *gin.Context) {
21            c.String(200, "User Profile")
22        })
23
24        // 嵌套子路由组
25        admin := private.Group("/admin")
26        admin.Use(AdminCheck())
27        {
28            admin.GET("/stats", func(c *gin.Context) {
29                c.String(200, "Admin Stats")
30            })
31        }
32    }
33
34    router.Run(":8080")
35}
36
37// 示例中间件
38func AuthMiddleware() gin.HandlerFunc {
39    return func(c *gin.Context) {
40        // 假设进行身份验证
41        if c.GetHeader("Authorization") == "" {
42            c.AbortWithStatus(401)
43            return
44        }
45        c.Next()
46    }
47}
48
49func AdminCheck() gin.HandlerFunc {
50    return func(c *gin.Context) {
51        // 检查管理员权限
52        if c.GetHeader("Role") != "admin" {
53            c.AbortWithStatus(403)
54            return
55        }
56        c.Next()
57    }
58}

通过合理使用路由组，可以显著提升 Gin 项目的结构清晰度，减少重复代码，并更高效地管理路由和中间件。