handlerfunc 是 func(*gin.context) 类型别名，非中间件类或 http.handler；c.next() 推进 handlers 切片索引执行后续 handler，需配合 c.abort() 和 return 终止链；handlerschain 由 use() 和路由注册拼接而成。
HandlerFunc 是什么，不是什么
gin.HandlerFunc 是一个函数类型别名，定义为 func(*gin.Context)。它不是中间件的“类”或“接口”，也不是标准库的 http.Handler —— 两者签名不同、行为不兼容。强行把 func(http.ResponseWriter, *http.Request) 类型函数传给 r.Use() 会触发 panic：“interface conversion: interface {} is …, not gin.HandlerFunc”。
你必须用 Gin 原生方式写：
func MyMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
// ...
}
}
- 返回值必须是
gin.HandlerFunc类型，不能是func()或其他闭包 - 参数只能是单个
*gin.Context，不能多参、不能少参 - 不能直接调用
c.Next()以外的“下一个中间件”——没有显式 next 参数，靠c.handlers切片和c.index隐式驱动
c.Next() 怎么触发链式执行
c.Next() 不是调用你传进去的某个函数，而是让 Gin 内部按序执行 c.handlers[c.index+1:] 中剩余的 handler。它本质是推进索引 + 调用当前 handler，不接受参数，也不返回值。
常见误解：c.Next() 不等于 “调用我写的下一个函数”，它只是“继续走链表里的下一个”。如果你在中间件里漏掉 c.Next()，后续所有中间件和最终路由 handler 都不会执行；如果重复调用（比如写了两次 c.Next()），会导致越界 panic 或跳过 handler。
- 只应在中间件逻辑分叉前调用一次，且通常放在中间位置（前置处理 →
c.Next()→ 后置处理） - 若想短路（如鉴权失败），绝对不要调用
c.Next()，而应直接c.Abort()或c.JSON()+return -
c.Next()返回后，c.handlers已执行完后续全部 handler，此时再访问c.Writer可能已写入响应头，不能再改状态码
Abort() 和 return 的区别很关键
c.Abort() 是 Gin 提供的链终止信号：它把 c.index 设为最大值，确保后续 c.Next() 不再执行任何 handler；但它不阻止当前函数继续往下跑。所以常配合 return 使用。
错误写法：
if !valid {
c.JSON(401, gin.H{"error": "no token"})
c.Abort() // 这行没用，下面 c.Next() 还会执行
}
c.Next()
正确写法：
if !valid {
c.JSON(401, gin.H{"error": "no token"})
c.Abort()
return // 必须 return，否则 c.Next() 仍会触发
}
-
c.Abort()改的是上下文状态，return才真正跳出当前函数栈 - 仅
return不调c.Abort()，后续中间件仍可能被执行（取决于注册顺序和是否检查c.IsAborted()） - 某些中间件（如
Recovery）内部会检查c.IsAborted()决定是否介入，所以c.Abort()是跨中间件通信的契约
HandlersChain 是怎么拼起来的
每个 *gin.Engine 或 *gin.RouterGroup 都有 handlers 字段，类型是 gin.HandlersChain，即 []gin.HandlerFunc。注册中间件时，Gin 把 handler 追加到这个切片末尾；匹配路由时，把路由 handler 也 append 进去，形成完整链。
例如：
r := gin.New()
r.Use(m1, m2)
r.GET("/api", handler)
实际构成的链是
[m1, m2, handler]。而 gin.Default() 默认带 Logger 和 Recovery，所以链更长。
- 全局
Use()注册的中间件对所有路由生效；路由组的Use()只影响该组内路由 - 同一个路由上多次
Use()，handler 按调用顺序追加，不是覆盖 - 链长度影响性能：每个 handler 都要分配栈、执行函数调用，高频接口建议精简中间件数量
*gin.Context 时的数据污染和时序依赖——比如一个中间件改了 c.Request.URL.Path，后面所有中间件和 handler 看到的就是新路径；又比如日志中间件读 c.Writer.Size()，但压缩中间件可能在它之后才写入真实 body。这些细节不报错，但结果难调试。
