Gin 没有内置控制器映射机制，所谓“控制器”需手动定义 struct 并显式绑定方法到路由；推荐用路由分组模拟命名空间，避免反射自动映射带来的维护与调试问题。
直接用 gin.Default() 配置路由是最简单的方式，但控制器映射这件事，Gin 本身不提供“自动扫描 controller 文件夹”或“按命名约定绑定方法”的机制——它压根没这个概念。所谓“控制器映射”，其实是你通过代码组织、路由分组和函数封装来模拟出来的。
为什么 Gin 没有内置控制器映射
Gin 是函数式路由框架，r.GET("/user", handlerFunc) 中的 handlerFunc 就是一个 func(*gin.Context) 类型函数。它不强制要求你把处理逻辑写在某个 struct 方法里，也不解析包路径或文件名去自动挂载。这意味着：
- 没有
Controller接口或基类，Go 语言本身也不支持类继承 - 所谓“控制器”，是你自己定义的 struct（比如
type UserController struct{}），然后手动把它的方法传给路由 - 所有“自动加载 controller”的能力，都来自第三方封装（如 GoFly）或你自己写的反射/遍历逻辑，不是 Gin 原生行为
如何手动实现控制器方法到路由的映射
最常用且可控的方式是：定义控制器 struct，暴露方法，再在路由注册时显式调用。关键点在于方法签名必须适配 func(*gin.Context)：
- 用闭包包装方法调用：
r.GET("/users", func(c *gin.Context) { (&UserController{}).List(c) }) - 或提前绑定实例：
uc := &UserController{svc: userService}，再r.GET("/users", uc.List) - 如果方法需要依赖注入（如 DB、缓存），推荐第二种方式，避免每次请求都新建 controller 实例
- 注意：Go 方法值（
uc.List）和方法表达式（UserController.List）类型不同，后者需显式传参，不能直接当 handler 用
用路由分组模拟控制器命名空间
虽然没控制器，但你可以用 gin.RouterGroup 让路由结构看起来像控制器。例如：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
api := r.Group("/api/v1")
{
user := api.Group("/users")
{
user.GET("", userHandler.List) // GET /api/v1/users
user.POST("", userHandler.Create) // POST /api/v1/users
user.GET("/:id", userHandler.Get) // GET /api/v1/users/123
}
post := api.Group("/posts")
{
post.GET("", postHandler.List)
}
}
这种写法让路径前缀 + handler 变量名共同构成语义上的“控制器上下文”。别依赖文件夹名或包名自动匹配——那只会让你后期改个路径就要同步改一堆地方。
避免踩坑：反射自动映射的代价
有些教程或框架（如 GoFly）用 reflect 扫描 struct 方法并按 HTTP 方法名（GetXXX、PostXXX）自动注册路由。这看似省事，但实际带来几个硬伤：
- IDE 跳转失效：点击 URL 路径无法定位到 handler 函数
- 启动变慢：每次运行都要遍历所有包、解析 AST 或反射类型
- 错误难排查：方法签名错一个参数，可能静默失败或 panic 在 runtime
- 测试困难：handler 不再是独立函数，mock 依赖链更重
除非团队明确接受这套约定并统一工具链，否则不建议在业务项目中引入反射式路由映射。
真正容易被忽略的是：路由和 handler 的耦合点永远在 r.XXX() 这一行代码里。把它写清楚、留注释、按功能聚合成组，比追求“自动”重要得多。
