Gin中间件函数签名必须为func(gin.Context)，无返回值，本质是接收gin.Context参数的函数；注册时需包装成gin.HandlerFunc类型，必须显式调用c.Next()移交控制权，否则后续中间件和handler不执行。
中间件函数签名必须返回func(*gin.Context)
Gin 的中间件本质就是一个接受 *gin.Context 参数、无返回值的函数，但注册时必须包装成 func(*gin.Context) 类型。常见错误是直接返回 error 或试图用 return 提前结束逻辑却忘了调用 c.Next() —— 这会导致后续 handler 完全不执行。
正确写法只有一条铁律：中间件内部必须显式调用 c.Next()（除非你明确想中断流程）。比如做权限校验，失败时应写 c.AbortWithStatusJSON(403, gin.H{"error": "forbidden"})，而不是 return。
-
c.Next()不是“继续下一个中间件”的可选操作，而是控制权移交的关键；不调它，链就断了 - 若中间件内 panic，Gin 默认 recover 会吞掉错误，需手动加
defer+recover()才能捕获日志 - 不要在中间件里重复解析
c.Request.Body—— Gin 默认只读一次，二次读会得到空内容
用c.GetHeader()和c.Query()安全提取过滤条件
请求过滤通常依赖 header（如 X-Api-Key）、query（如 ?env=prod）或 path 参数。直接用 c.Request.Header.Get("X-Api-Key") 有风险：大小写敏感、可能为空、没做 trim。Gin 提供了更健壮的封装。
c.GetHeader("X-Api-Key") 自动忽略大小写并返回空字符串而非 nil；c.Query("env") 比 c.Request.URL.Query().Get("env") 更安全，它已处理 URL 解码和空值。
立即学习“go语言免费学习笔记（深入）”；
- header 值建议用
strings.TrimSpace()再判断，避免前端传入带空格的 key -
c.DefaultQuery("env", "dev")可设默认值，比手写if v == "" { v = "dev" }更简洁 - 若需校验 IP 白名单，别用
c.ClientIP()直接比对 —— 它受GIN_MODE和反向代理影响，应配合c.Request.RemoteAddr和可信 proxy 列表一起用
避免在中间件里阻塞主线程（尤其 JWT 解析）
常见做法是在中间件里解析 JWT 并验证签名，但若用同步 IO 或未缓存公钥，高并发下会拖慢整个路由链。Gin 是同步模型，中间件里任何耗时操作都会卡住 goroutine。
真正轻量的过滤（如白名单 IP、固定 token）可以放中间件；但涉及网络请求（如远程校验 token）、文件读取（如每次读 pem 文件）、或复杂解密（如 RSA 验签），必须提前预热或异步化。
- JWT 公钥建议在应用启动时加载进内存，用
sync.Once初始化，而非每次请求都ioutil.ReadFile - 如果必须远程校验，改用 “token 预检 + 异步刷新” 模式：中间件只查本地 cache，过期再后台更新
- 不要在中间件里调
time.Sleep()做限流 —— 应用级限流请用golang.org/x/time/rate的RateLimiter，且需绑定到 context
注册顺序决定过滤生效范围
Gin 中间件注册顺序 = 执行顺序。全局中间件（r.Use(mw1, mw2)）对所有路由生效；分组中间件（v1.Use(auth)）只作用于该 group 下的路由；而单个 handler 的中间件（r.GET("/ping", logger, pingHandler)）仅对该 endpoint 生效。
一个典型陷阱：把鉴权中间件放在日志中间件之后，结果日志里看不到未授权请求的完整路径 —— 因为鉴权失败后 c.Abort()，日志中间件里的 c.Next() 后续代码根本不会执行。
- 通用过滤（如 CORS、日志）适合全局注册；业务过滤（如租户隔离、权限）优先用分组注册
- 若某中间件依赖前序中间件设置的 context value（如
c.Set("user_id", 123)），必须确保它排在设置者之后 - 调试时可用
fmt.Printf("middleware %s start\n", name)+defer fmt.Printf("middleware %s end\n", name)快速定位执行顺序问题
最易被忽略的是中间件的“副作用清理”：比如你在中间件里修改了 c.Request.Header，后续 handler 可能意外依赖这个改动；或者用了 c.Set() 却没在最后 c.Reset()，导致 context 复用时数据污染。Gin 的 context 不是完全隔离的，尤其在测试或压测中容易暴露这类问题。
