Gin控制器方法必须用值接收器且参数仅为*gin.Context，结构体不可含状态字段；正确做法是预创建带依赖的实例并复用，避免字面量调用导致依赖丢失或反射失败。
控制器必须是值类型调用，不能用指针接收器
直接用 AdminController{} 实例调用方法（如 admin.AdminController{}.Index），是 Gin 控制器能正常工作的前提。如果把方法定义成指针接收器：func(c *AdminController) Index(...)，再用 &admin.AdminController{} 传参，Gin 会因反射机制无法正确绑定而静默失败——路由注册看似成功，但请求进来时 panic 或返回 404。
原因在于 Gin 的 router.GET(..., handler) 最终通过 reflect.Value.Call 执行 handler，它要求 handler 是一个可直接调用的函数值；而指针接收器方法在 Go 反射中属于“未导出方法绑定”，除非显式取地址并确保实例存活，否则容易触发 nil 指针或类型不匹配。
- ✅ 正确写法：
func(c AdminController) Index(c *gin.Context)+admin.AdminController{}.Index - ❌ 错误写法：
func(c *AdminController) Index(...)+new(admin.AdminController).Index（尤其在无显式初始化时极易出错） - ⚠️ 注意：即使你用指针接收器写了方法，只要没在路由里传
&admin.AdminController{}，而是继续用admin.AdminController{}.Method，Go 会自动取地址调用——但这属于隐式行为，可读性差且易被 lint 工具报错
控制器方法参数只能是 *gin.Context，不能加其他参数
Gin 路由注册时只接受签名形如 func(*gin.Context) 的函数。控制器方法如果多加一个参数，比如 func(c AdminController, id string)，编译会通过，但运行时注册失败，Gin 不会校验，只会导致该路由永远 404 —— 因为 admin.AdminController{}.AdminList 这个表达式生成的是一个闭包，其底层类型不是 gin.HandlerFunc。
需要访问 URL 参数、表单、JSON body 等，一律通过 c.Param("id")、c.Query("page")、c.ShouldBindJSON(&req) 等 *gin.Context 方法获取。
- ✅ 正确：所有业务逻辑从
c上取数据，例如id := c.Param("id") - ❌ 错误：试图让 Gin 自动注入参数，如
func(c AdminController, id uint)（Gin 不支持依赖注入） - ? 小技巧：把常用解析逻辑封装成私有方法，比如
parseAdminID(c *gin.Context) (uint, error)，避免每个 handler 重复写strconv.ParseUint(c.Param("id"), 10, 64)
控制器结构体本身不应带状态，避免并发问题
看起来给 AdminController 加个字段 db *sql.DB 很自然，但这是危险操作。因为 admin.AdminController{}.Index 每次都是新实例，如果你在结构体里存了连接、缓存、锁等，不仅浪费内存，更可能因未初始化或竞态访问引发 panic。
Gin 的 handler 是无状态的，控制器结构体只是组织方法的命名空间。真正需要共享的资源（数据库、Redis 客户端、配置）应通过依赖注入或全局变量传入，而不是塞进控制器字段。
- ✅ 推荐方式：在初始化控制器时传入依赖，例如
admin.NewAdminController(db, cache)返回一个带字段的实例，然后用闭包包装 handler：func(c *gin.Context) { ctrl.Index(c) } - ❌ 反模式：直接在结构体里声明
db *sql.DB并期望每次调用都可用——没有初始化逻辑，运行时 nil dereference 几乎必然发生 - ⚠️ 特别注意：不要在控制器里用
sync.Mutex字段做请求间同步，Gin 的每个请求都在独立 goroutine，锁毫无意义，还可能造成死锁
路由分组注册时，避免重复创建控制器实例
看这个常见写法：adminRouter.GET("list", admin.AdminController{}.AdminList) —— 每次注册一个路由，就 new 一次空结构体。虽然开销极小，但当路由上百条时，会生成大量无意义对象，且不利于后续统一注入依赖（比如日志实例、DB 连接）。
更可控的做法是提前构造好控制器实例，复用它注册多个路由：
ctrl := admin.NewAdminController(db, logger)
adminRouter.GET("list", ctrl.AdminList)
adminRouter.POST("add", ctrl.AddAdmin)
adminRouter.PUT("update", ctrl.UpdateAdmin)
这样既能保证依赖一致，又避免了零散初始化。如果控制器确实不需要任何依赖，用空结构体也无妨，但风格上建议统一。
复杂点在于：一旦用了带依赖的控制器实例，就不能再用 admin.AdminController{}.Method 这种字面量写法，否则会丢失依赖上下文——这点很容易被忽略，尤其在团队协作时，有人随手改回字面量，bug 就埋下了。
