常见坑汇总：路由冲突、中间件顺序、绑定失败静默、timeout 遗漏等

这一章把 Gin 日常开发里最容易踩的坑集中讲透，每个坑都给「现象 → 原因 → 正确写法」，行为以 gin 官方文档为准。

1. 路由冲突

gin 的路由树对参数与通配符位置敏感：

r.GET("/users/:id", h)
r.GET("/users/:name", h) // panic：同一层第二个参数名与已有 :id 冲突

r.GET("/files/*path", h)    // 合法：* 匹配 /files/a/b 整段
// r.GET("/files/*a/b", h)  // panic：通配符必须是路径最后一段

// 静态段与参数段可共存，匹配时静态优先，
// 建议先注册静态路由（如 /users/me）再注册参数路由

通配符 * 只能作最后一段且独占整段；同层参数名必须一致才能复用。

2. 中间件顺序与 c.Next()

中间件按注册顺序执行，c.Next() 之前是「请求前」，之后是「响应后」：

func Timing() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        c.Next() // 执行后续中间件与 handler
        log.Printf("%s took %v", c.Request.URL.Path, time.Since(start))
    }
}

漏写 c.Next() 链条直接中断；已写响应或 Abort 后记得 return。

3. 绑定失败静默

c.Bind 系失败会自动写 400，但 ShouldBind 系失败只返回错误、不自动响应，很多新手把错误吞了：

if err := c.ShouldBindJSON(&in); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": "参数格式错误"})
    return // 别忘了 return！
}

空 body 绑 JSON 会得到 EOF 类错误，也要按 400 处理。

4. 忘记超时

两个典型遗漏：

// 1) 外部调用不设超时：下游慢，请求就挂住
ctx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
defer cancel()
val, err := rdb.Get(ctx, key).Result()

// 2) http.Server 不设读写超时：慢客户端占满连接
srv := &http.Server{
    Addr:         ":8080",
    Handler:      r,
    ReadTimeout:  10 * time.Second,
    WriteTimeout: 10 * time.Second,
}
srv.ListenAndServe()

5. 其他高频坑

• r.Run() 默认监听 :8080，部署时常因地址/端口写错连不上；
• handler 里起 goroutine 还写 c，产生数据竞争（见并发章节）；
• GORM v2 对无条件的批量 Delete/Updates 会拒绝执行（缺少 Where 条件），这是防误删的设计；
• 生产忘关 debug 输出、日志里打敏感字段。

注意点

• gin.New() 不带任何中间件，请 r.Use(gin.Recovery()) 防 panic 拖垮进程，或直接用 gin.Default()。
• 路由先设计好参数形状，别靠注册顺序“救场”。

小结

多数坑集中在三处：路由树规则、中间件/绑定的执行语义、超时与生命周期。记住「ShouldBind 要自己处理错误」「外部调用要带超时」「c.Next 决定链是否走完」，能避开大半生产事故。