gorilla/mux被选用是因为其中间件链完全显式、无黑盒，每个中间件必须手动包装handler并明确控制执行顺序与短路逻辑，避免Gin/Echo中隐式注册导致的调试困难；mux路由不自动继承中间件，需显式应用，确保控制流清晰可追溯。
为什么不用 Gin/Echo 而选 gorilla/mux 做中间件链
因为 mux 本身不封装 handler 执行逻辑，只做匹配和委托，所有中间件都是显式 compose 的——你清楚每一层谁先谁后、谁可能 panic、谁改了 context 或 ResponseWriter。Gin 的 Use() 看似简洁，但中间件顺序隐含在注册时机里，出问题时很难定位是 authMiddleware 没放行，还是 recoverMiddleware 捕获太晚。
关键区别在于：mux 的中间件必须手动包装 handler，没有“自动注入”；而框架类库常把中间件变成黑盒钩子，容易掩盖错误传播路径。
- 标准库
http.Handler接口是func(http.ResponseWriter, *http.Request)，mux 的Router也实现它，所以你能用任意中间件函数套一层再传给r.HandleFunc - 不要写
r.Use(authMiddleware)—— mux 没这方法。正确姿势是r.HandleFunc("/user", authMiddleware(userHandler)) - 中间件返回的 handler 必须是
http.Handler类型，不能直接 returnfunc(...)，否则编译失败
如何写一个可复用的中间件并接入 mux 链
典型误区是中间件里直接 w.WriteHeader(401) 就 return，结果下游 handler 还继续执行。真正可控的中间件要基于“短路”逻辑：只在条件不满足时提前结束，否则调用 next。
func loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
log.Printf("incoming: %s %s", r.Method, r.URL.Path)
next.ServeHTTP(w, r) // 不加这一行，下游永远不会执行
})
}
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "missing auth header", http.StatusUnauthorized)
return // 短路，不往下走
}
// 注入 context，供下游读取
ctx := context.WithValue(r.Context(), "user_id", "123")
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
- 每个中间件都必须返回
http.Handler，推荐用http.HandlerFunc包装 - 修改
*http.Request（如加context）必须用r.WithContext()生成新 request，原对象不可变 - 不要在中间件里调
http.Redirect后还调next.ServeHTTP，会导致 write after write header 错误
mux 路由匹配与中间件作用域的关系
很多人以为 r.PathPrefix("/api").Subrouter() 创建的子路由能自动继承父级中间件——其实不会。mux 的中间件只对显式注册的 handler 生效，子 router 是独立实例，必须单独包装。
立即学习“go语言免费学习笔记（深入）”；
比如你希望所有 /api/ 下路径都走日志 + 鉴权，但 /health 不走：
r := mux.NewRouter()
// 全局健康检查，不进中间件
r.HandleFunc("/health", healthHandler)
// api 子路由，显式套中间件
api := r.PathPrefix("/api").Subrouter()
api.HandleFunc("/users", loggingMiddleware(authMiddleware(usersHandler)))
api.HandleFunc("/orders", loggingMiddleware(authMiddleware(ordersHandler)))
// 或批量注册（更清晰）
api.Use(loggingMiddleware, authMiddleware) // ❌ mux 没这个方法！这是常见误写
// 正确做法是封装一个 applyMiddleware 工具函数
-
Subrouter()返回的是新*mux.Router，和父 router 完全无关 - 想复用中间件链？写个辅助函数：
applyMiddlewares(handler http.Handler, mws ...func(http.Handler) http.Handler) http.Handler - 别依赖路径前缀自动拦截——mux 不做运行时拦截，只做静态匹配
中间件顺序错位导致的典型问题
最常踩的坑是 recoverMiddleware 放得太靠后：如果 authMiddleware panic 了，recoverMiddleware 根本没机会执行，整个请求就 crash 掉。
正确顺序应该是：日志 → 恢复 → 鉴权 → 限流 → 业务 handler。recover 必须在所有可能 panic 的中间件之前。
- panic 发生在
next.ServeHTTP调用中，所以 recover 中间件必须 wrap 在它外层 - 限流中间件如果依赖 Redis，网络超时会 panic，它必须被 recover 包住
- 不要把
context.WithTimeout放在中间件最后——应该在最外层就建好带 timeout 的 ctx，然后透传下去 - 打印日志的中间件放在最外层，否则 recover 后无法记录原始 path 和 method
中间件不是功能堆叠，是控制流契约：每层都承诺“要么终止请求，要么确保 next 执行”。漏掉 return 或多调一次 next.ServeHTTP，都会让行为变得不可预测。
