Gin中间件必须是gin.HandlerFunc类型，Use()会严格断言类型，错误传参导致panic；c.Next()是同步阻塞点，c.Abort()终止流程，c.Copy()保障goroutine安全，闭包注入配置避免硬编码。
中间件必须是 gin.HandlerFunc 类型，否则注册就 panic
传错类型是 Gin 中间件最常卡死的第一步。Gin 的 Use() 方法会做严格类型断言，如果传入的是普通函数、带参数的闭包、或返回值不是 gin.HandlerFunc 的函数，运行时直接 panic，错误类似 panic: interface conversion: interface {} is func(), not gin.HandlerFunc。
- 正确写法：定义函数返回
gin.HandlerFunc，且内部签名必须是func(c *gin.Context) - 错误写法：
func auth(c *gin.Context, role string)（多参数）、func() {}（无参）、authMiddleware("admin")少括号（传函数地址而非执行结果） - 安全写法示例：
func AuthMiddleware() gin.HandlerFunc { return func(c *gin.Context) { // ... c.Next() } }然后调用r.Use(AuthMiddleware())，注意末尾有括号
c.Next() 和 c.Abort() 控制流程，顺序错一位就失效
中间件链是洋葱模型，但“层”不是框架自动调度的，全靠你手动放 c.Next() 的位置。它不是自动往下走，而是同步阻塞执行后续所有中间件和 handler，等它们全部返回后才继续执行 c.Next() 后面的代码。
- 鉴权类中间件必须在
c.Next()前校验，失败时调c.Abort()—— 不调c.Next()，也不 return，否则请求仍会穿透到业务 handler - 日志中间件想统计耗时，就得把计时起点放
c.Next()前、终点放c.Next()后 - Recovery 中间件必须在 Auth 之前注册，否则 Auth 内部 panic 无法被捕获；但又不能放在某个 Group().Use() 里，否则只对分组生效，全局 panic 还是崩
- 常见翻车：把 CORS 放在 Recovery 后面，结果 CORS header 没写上就被 Recovery 拦了
读请求头、改请求体、存上下文，每一步都有陷阱
看似简单的取头、解析、设值，实际踩坑密集。Gin 的 *gin.Context 是复用对象，字段可变，但底层 http.Request 和 Body 是一次性流。
- 取头别硬写
c.Request.Header.Get("X-Api-Key")—— HTTP 头大小写不敏感，但 Go 默认按原样匹配，建议统一转小写：strings.ToLower(c.Request.Header.Get("X-API-KEY")) - 需要多次读
c.Request.Body（比如先校验再 bind）？必须提前io.ReadAll()缓存，并用io.NopCloser()替换：c.Request.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))，否则下游c.ShouldBindJSON()读不到内容 - 鉴权成功后要传用户信息给下游，必须显式
c.Set("user", user)；下游用c.MustGet("user").(User)取，但前提是这个中间件已在链中且已执行 - 在 goroutine 里用
c？必须c.Copy()，否则主线程返回后原上下文字段被清空，协程里读到全是零值
闭包传参是刚需，但别把密钥/配置硬编码进函数体
真实项目几乎没有“裸中间件”。权限前缀、白名单路径、JWT 密钥、日志级别……全得动态注入。闭包是唯一自然的解法，但容易把敏感信息写死。
立即学习“go语言免费学习笔记（深入）”；
- 正确模式：
func AuthMiddleware(requiredRole string, secretKey []byte) gin.HandlerFunc，参数从环境变量或配置中心加载，不在函数体内硬编码 - 别在中间件里直接写
if token == "abc123"—— 密钥泄漏风险高，且无法热更新 - 代理透传场景下，
X-Forwarded-For或X-Real-IP可能被伪造，需配合TrustedProxies设置可信 IP 段 - body 解密类中间件，替换
c.Request.Body后必须确保新 Body 实现io.ReadCloser，否则下游框架 panic
c.Next() 是同步阻塞点、c.Abort() 是终止开关、c.Copy() 是协程保命符——这些控制点一旦错位，整个链路行为就不可预期。 
