中间件函数为什么必须返回 http.Handler 或接受 http.Handler 参数
go 的 HTTP 中间件本质是“包装器”——它不直接处理请求，而是把原始 handler 包一层再交出去。如果你写了个函数但没返回新的 http.Handler，或者没接收一个 http.Handler 作为参数，那它根本没法接入标准的 http.ServeMux 或 http.ListenAndServe 流程。
常见错误现象：cannot use myMiddleware (type func(http.ResponseWriter, *http.Request)) as type http.Handler。这说明你定义的是个裸 handler，不是中间件。
- 正确模式：中间件函数签名通常是
func(http.Handler) http.Handler，比如loggingMiddleware、authMiddleware - 调用时要链式传入：先包最内层业务 handler，再一层层往外套，顺序决定执行顺序
- 别在中间件里直接调用
next.ServeHTTP(w, r)后还继续写响应，容易触发http: multiple response.WriteHeader calls
如何让多个中间件按预期顺序执行（尤其日志 + 认证 + 路由）
Go 没有内置中间件栈概念，顺序完全靠你手动嵌套或用辅助函数控制。最容易出错的是把认证中间件放在日志之后却忘了它可能提前终止请求，导致日志没打全、或路由根本没走到。
使用场景：比如你希望每次请求都先打日志、再校验 Token、最后才进业务逻辑。如果把 authMiddleware 放在最外层，它拦截后就不会进日志；放最里层又失去了保护意义。
立即学习“go语言免费学习笔记（深入）”；
- 推荐写法：用变量逐步包装，从内到外清晰可读：
h := authMiddleware(loggingMiddleware(homeHandler)) - 避免用匿名函数嵌套多层，调试时堆栈难追踪；也别依赖第三方库自动排序，除非你真清楚它怎么 resolve 依赖
- 注意：中间件内部调用
next.ServeHTTP是同步阻塞的，前一个不 return，后一个不会执行
http.HandlerFunc 和 http.Handler 在中间件中怎么转换
很多初学者卡在类型转换上。标准库里 http.HandlerFunc 是个类型别名，实现了 ServeHTTP 方法，所以能当 http.Handler 用；但反过来不行——你不能把一个普通函数当 http.Handler 直接传给中间件，除非它满足接口契约。
参数差异直接影响能否链起来：
- 业务 handler 常写成
func(w http.ResponseWriter, r *http.Request)，这是http.HandlerFunc类型，可直接转为http.Handler - 中间件接收的必须是
http.Handler接口，所以你可以传http.HandlerFunc(myHandler)或直接传已实现该接口的 Struct 实例 - 别试图对中间件返回值做类型断言，比如
h.(http.HandlerFunc)，它大概率 panic —— 返回的是闭包，不是函数字面量
为什么中间件里 recover panic 失效，或者日志时间戳总不准
这不是语法问题，而是执行时机和作用域理解偏差。比如你在中间件里 defer 一个 recover()，但它只捕获当前 goroutine 内部 panic；而 HTTP server 启动后每个请求都在独立 goroutine 运行，中间件里的 defer 确实能生效——但前提是 panic 发生在 next.ServeHTTP 调用期间，且你没在中间件里自己启动新 goroutine。
性能与兼容性影响：时间戳不准往往是因为用了 time.Now() 多次，而 Go 的 time.Now() 虽然快，但在高并发下仍可能因调度延迟造成微小偏差；更关键的是，如果你在中间件开头记一次时间、结尾再记一次，中间的 next.ServeHTTP 可能被长耗时操作阻塞，导致统计失真。
- recover 生效前提：defer 必须在同一个函数作用域内，且 panic 发生在 defer 所在 goroutine 的后续调用栈中
- 时间统计建议：统一用
time.Now()开头取基准，结尾用time.Since(start)，避免多次系统调用 - 别在中间件里做重 IO 操作（如写文件日志），会拖慢整个链路；优先用结构化日志库异步刷盘
真正麻烦的是中间件之间共享状态——比如想把用户 ID 从认证中间件透传到日志中间件，得靠 context.WithValue，但很多人漏了 context 传递，或者用了非导出 key 导致取不到值。这个点不报错，但逻辑就断了。