Go HTTP中间件本质是http.Handler链式包装，通过函数接收并返回Handler实现逻辑插入；需显式拼接、注意执行顺序、调用next.ServeHTTP、用闭包传参、自定义ResponseWriter拦截响应。
Go HTTP 中间件的本质是 http.Handler 链式包装
Go 的中间件不是框架内置概念，而是基于 http.Handler 接口的函数式组合。每个中间件接收一个 http.Handler，返回一个新的 http.Handler，在调用下游前/后插入逻辑。这不是语法糖，而是标准库设计的自然延伸。
常见错误是试图“注册”中间件到某个全局容器，或期待类似 Express 的 app.use() 顺序自动生效——Go 里必须显式拼接：
handler := loggingMiddleware(authMiddleware(homeHandler))
http.ListenAndServe(":8080", handler)
- 顺序很重要：越靠外的中间件越先执行（请求进入时），也越后执行（响应返回时）
- 必须调用
next.ServeHTTP(w, r)，否则请求链中断，下游 handler 永远不会运行 - 不要在中间件里直接写
w.Write()后就 return，除非你明确想终止链（比如认证失败返回 401）
用闭包捕获配置参数比硬编码更安全
中间件常需外部配置，比如日志前缀、JWT 密钥、超时时间。直接写死会导致复用困难，测试难 mock。推荐用闭包封装初始化逻辑：
func timeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), timeout)
defer cancel()
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
}
// 使用
handler := timeoutMiddleware(5 * time.Second)(homeHandler)
- 闭包返回的是“中间件工厂”，每次调用生成新实例，避免共享状态污染
- 参数类型要明确（如
time.Duration），别用string再解析，易出错且难维护 - 注意
context.WithTimeout创建的 ctx 必须传给下游 request，否则超时无效
自定义 http.ResponseWriter 是拦截响应的关键手段
想记录响应状态码、耗时、Body 大小？标准 http.ResponseWriter 不提供读取能力。必须包装它，实现自己的 ResponseWriter：
立即学习“go语言免费学习笔记（深入）”；
type responseWriter struct {
http.ResponseWriter
statusCode int
written bool
}
<p>func (rw *responseWriter) WriteHeader(code int) {
rw.statusCode = code
rw.written = true
rw.ResponseWriter.WriteHeader(code)
}</p><p>func (rw *responseWriter) Write(b []byte) (int, error) {
if !rw.written {
rw.WriteHeader(http.StatusOK)
}
return rw.ResponseWriter.Write(b)
}
- 必须重写
WriteHeader和Write，否则状态码可能被忽略（比如 panic 后默认 200） - 不能只依赖
WriteHeader判断是否已写，有些 handler 只调Write（隐式 200），所以需标记written - 别在中间件里读取或修改原始
ResponseWriter的底层连接（如http.Hijacker），会破坏升级协议（WebSocket）
第三方中间件（如 gorilla/handlers）只是封装，不改变底层模型
gorilla/handlers 提供了 LoggingHandler、CORS 等开箱即用中间件，但它们仍是标准 func(http.Handler) http.Handler 类型。引入它不等于引入“框架”，只是省去重复造轮子。
典型误用是混用多个中间件包的写法，比如把 chi.MiddlewareFunc 和 gorilla/handlers 直接串一起——类型不兼容，编译报错：
// ❌ 错误：类型不匹配 handler := gorilla.Handlers.LoggingHandler(os.Stdout, chiMux) // chiMux 不是 http.Handler
- 确认目标中间件接受的参数类型，
gorilla/handlers全部接收http.Handler，而chi的中间件是func(http.Handler) http.Handler，可直接混用 - 生产环境慎用未维护的中间件包，比如某些 GitHub 上 star 很高但两年没更新的 CORS 实现，可能不支持
Access-Control-Allow-Credentials: true场景 - 真正复杂的中间件逻辑（如熔断、分布式追踪）建议用专用 SDK（如 OpenTelemetry Go SDK），而非手写
中间件链的调试难点在于“谁改了 status code”或“谁提前写了 response”。最有效的办法是在关键中间件里加 log.Printf("before %s, status=%d", middlewareName, rw.statusCode)，而不是依赖最终日志。
