必须拆分单个 router.go 文件,按模块(如 user、order)分离路由与控制器,通过 Group() 实现路径与中间件双重隔离,并确保模块注册函数接收 *gin.RouterGroup 参数以支持测试与多版本共存。

路由文件爆炸前必须拆分
单个 router.go 超过 300 行、所有模块路由挤在 main() 里注册,是 Gin 项目维护恶化的明确信号。这不是“能跑就行”的问题,而是每次加一个接口都要全局搜索路径前缀、改中间件得翻遍整个文件、版本升级时 v1/v2 路由混在一起无法隔离——直接导致上线前漏配中间件或路径冲突。
核心动作就一条:把 router.Group() 的调用从 main.go 移出去,每个业务模块(如 user、order)单独建 api/router/user.go 和 api/controller/user.go,再通过一个总入口 api/router/router.go 统一挂载。
-
api/router/router.go只做两件事:初始化gin.Engine(或接收已初始化的*gin.Engine),调用各模块的注册函数(如user.RegisterRoutes(r.Group("/users"))) - 模块路由文件(如
user.go)只暴露一个注册函数,接收*gin.RouterGroup,内部只写本模块的.GET/.POST等调用 - 绝对不要在模块路由里调用
gin.Default()或重复初始化中间件——那是总入口的事
用 Group() 做路径和中间件双重隔离
单纯按功能拆文件还不够,Group() 是 Gin 提供的原生隔离机制,不利用它等于放弃框架最实用的工程能力。路径前缀和中间件绑定必须同步设计,否则权限控制会漏掉或误加。
比如管理后台接口,不能只写 r.Group("/admin"),而要立刻绑定中间件:
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
admin := r.Group("/admin", authMiddleware(), casbinMiddleware())
{
admin.GET("/users", listUsers)
admin.POST("/users", createUser)
}
- 路径前缀(如
/api/v2、/webhook)和中间件(如jwtAuth()、rateLimit())必须在同一层Group()中声明,避免后续有人只加路由不加中间件 - 不要嵌套多层 Group(如
r.Group("/api").Group("/v1").Group("/users")),这会让实际路径变成/api/v1/users却难以追溯前缀来源;推荐扁平化:直接r.Group("/api/v1/users") - 全局中间件(如日志、panic 恢复)走
r.Use(),局部中间件必须走Group()的第二个参数列表
模块注册函数必须接收 *gin.RouterGroup 参数
常见错误是模块路由文件自己 new 一个 engine 或直接操作全局 router 实例,导致测试时无法 mock、单元测试难覆盖、多版本路由无法并存。
正确做法是让每个模块暴露一个纯函数,输入是路由组,输出是 void:
// api/router/user.go
func RegisterRoutes(rg *gin.RouterGroup) {
rg.GET("", listUsers)
rg.POST("", createUser)
rg.GET("/:id", getUser)
}
- 总入口
api/router/router.go调用时传入具体 group:user.RegisterRoutes(r.Group("/users")) - 测试该模块路由时,可传入 mock 的
*gin.RouterGroup,无需启动 HTTP server - 如果某模块需同时支持 v1/v2,只需两次调用:
user.RegisterRoutes(r.Group("/api/v1/users"))和user.RegisterRoutes(r.Group("/api/v2/users")),逻辑完全复用
容易被忽略的初始化顺序和 panic 捕获点
很多人把中间件注册、路由挂载、服务启动写成线性代码,却没注意 Gin 的 Recovery() 中间件默认只包裹 router.Run() 启动后的请求链,而路由注册阶段的 panic(比如 controller 函数名拼错、空指针解引用)会直接 crash 进程,根本不会进 Recovery。
- 所有 handler 函数(如
listUsers)必须在路由注册前定义完毕,否则运行时报nil pointer dereference - 若用反射自动扫描 handler,务必在
main()开头就完成注册,而不是在RegisterRoutes()里动态加载——后者会让 panic 发生在路由挂载过程中,无法被 Recovery 捕获 - 建议在总路由入口
router.go最后加一行log.Println("routes registered successfully"),确保 panic 发生在启动前就能被日志捕获,而不是等第一个请求进来才暴露










