应使用gin.New()创建空引擎并手动挂载中间件，而非直接用gin.Default()；需按日志→恢复→鉴权→CORS顺序注册，路由分组须显式挂载中间件，权限控制必须依赖中间件而非路径前缀。
如何用 gin.Default() 初始化一个可扩展的后台API服务
直接用 gin.Default() 启动服务没问题，但后台管理系统必须考虑中间件链、路由分组和错误统一处理——否则加个JWT鉴权或日志就容易乱套。
真正可用的初始化方式是拆开两步：gin.New() 创建空引擎，再手动挂载必需中间件。比如：
r := gin.New() r.Use(gin.Logger()) r.Use(gin.Recovery()) r.Use(jwtMiddleware()) // 自定义JWT中间件 r.Use(corsMiddleware())
-
gin.Default()自带 Logger 和 Recovery，但 Recovery 会吞掉 panic 详情，不利于排查权限校验失败这类逻辑问题 - 所有中间件顺序不能错：日志要在最前，鉴权在路由匹配之后、handler 执行之前
- 如果用了 GORM，别在中间件里初始化 DB 实例；应在
main()中完成连接池配置并注入到全局或 context
用户管理 API 的路由设计与参数绑定陷阱
RESTful 路由不是写对 HTTP 方法就行，GET /users 和 GET /users/:id 共享 handler 时，:id 参数类型不校验就会导致 500 或静默失败。
推荐写法：
立即学习“go语言免费学习笔记（深入）”；
userGroup := r.Group("/api/v1/users")
{
userGroup.GET("", listUsersHandler) // 查询列表，支持 ?page=1&limit=20
userGroup.POST("", createUserHandler) // 创建
userGroup.GET("/:id", getUserHandler) // 单条查询，id 必须是 uint64 或 int64
userGroup.PUT("/:id", updateUserHandler)
userGroup.DELETE("/:id", deleteUserHandler)
}
-
getUserHandler中必须显式调用c.Param("id")并转成整型，strconv.ParseUint(c.Param("id"), 10, 64)，否则字符串直接进 DB 查询会报错或绕过权限 - 列表接口的分页参数建议用
c.Query("page")+c.DefaultQuery("limit", "10")，避免空值引发 panic - 不要把密码字段塞进
gin.H{}返回，哪怕已加密——Gin 不会自动过滤 struct tag，得靠自定义返回结构体或 map 过滤
JWT 鉴权中间件里最容易漏掉的三件事
很多项目把 JWT 解析完就 c.Next()，结果角色权限没校验、token 过期没拦截、上下文传参不一致，导致接口裸奔。
一个最小可行的鉴权中间件应包含：
func jwtAuth() gin.HandlerFunc {
return func(c *gin.Context) {
authHeader := c.GetHeader("Authorization")
if authHeader == "" {
c.AbortWithStatusJSON(401, gin.H{"error": "missing token"})
return
}
tokenString := strings.TrimPrefix(authHeader, "Bearer ")
token, err := jwt.ParseWithClaims(tokenString, &jwt.StandardClaims{}, func(t *jwt.Token) (interface{}, error) {
return []byte(os.Getenv("JWT_SECRET")), nil
})
if err != nil || !token.Valid {
c.AbortWithStatusJSON(401, gin.H{"error": "invalid or expired token"})
return
}
claims := token.Claims.(*jwt.StandardClaims)
c.Set("user_id", claims.Subject) // 必须设，后续 handler 依赖
c.Set("role", getRoleFromDB(claims.Subject)) // 角色查库或缓存，别硬编码
c.Next()
}
}
- 没做
c.AbortWithStatusJSON()就直接 return，会导致后续 handler 继续执行，权限形同虚设 -
claims.Subject通常存的是用户 ID，但若后端用邮箱做 subject，前端没对齐就会查不到用户 - 角色信息别只存在 token payload 里——万一权限变更，旧 token 还在有效期内，得靠运行时查库或 Redis 缓存做二次校验
为什么 router.AddRoute() 不适合动态权限路由
前端传角色码、后端动态拼路由再 r.AddRoute()，看似灵活，实则破坏 Gin 的路由树结构，且并发添加时可能 panic。
Gin 的路由注册是初始化阶段一次性完成的，AddRoute() 是内部方法，未公开为安全 API。真要实现动态权限，正确做法是：
- 所有路由照常注册，但每个 handler 开头加权限检查：从 context 取
role，比对硬编码的requiredRoles = []string{"admin", "editor"} - 或者用 Casbin 做外部策略管理，
enforcer.Enforce(sub, obj, act)判断"user_123" / "/api/v1/users" / "POST"是否允许 - 绝对不要在登录成功后调用
r.AddRoute()—— 它不线程安全，且 Gin 的tree结构不允许运行时修改
动态路由本质是前端控制展示，后端只管“能不能进”，而不是“让不让注册”。混淆这两层，后期维护成本会指数级上升。
