Go语言中间件教程：HTTP请求拦截技巧

本文深入剖析了Go语言中HTTP中间件编写的底层原理与实战陷阱，强调中间件本质是符合`func(http.Handler) http.Handler`签名的函数链式封装，而非语法糖；重点揭示了提前终止请求必须显式`return`、`r.Body`只能读取一次需手动缓存、`panic`必须在`defer`中安全捕获并立即响应等极易被忽视却关乎系统稳定性的关键细节，直击高并发场景下因状态流转失控（如header重复写入、body耗尽、context中断）引发的隐蔽故障，为开发者提供可落地的健壮中间件编写准则。

中间件必须返回 http.Handler，否则链路就断了

Go 没有“中间件”语法糖，它只是函数套函数：输入一个 http.Handler，输出另一个 http.Handler。写成普通函数不返回 handler，或者返回类型写成 func(http.ResponseWriter, *http.Request) 却没转成 http.HandlerFunc，都会导致编译失败或运行时 panic。

常见错误写法：
func auth(next http.Handler) { ... } —— 没返回值，http.ListenAndServe 接收不到有效 handler
func auth(next http.Handler) func(http.ResponseWriter, *http.Request) { ... } —— 类型不匹配，无法直接嵌套

• 正确签名必须是 func(http.Handler) http.Handler 或 func(http.HandlerFunc) http.HandlerFunc
• 用 http.HandlerFunc 包裹闭包是最轻量、最常用的方式
• 如果下游是自定义 struct 实现的 http.Handler（比如实现了 ServeHTTP 方法），中间件也得接收 http.Handler 接口，不能只认 http.HandlerFunc

拦截请求后要提前终止？必须 return，且不能调用 next.ServeHTTP()

鉴权失败、参数校验不通过、限流触发——这些场景下你得主动写响应并退出，否则请求会继续往下走，造成逻辑错乱甚至数据泄露。

典型错误：
if token == "" { http.Error(w, "Unauthorized", http.StatusUnauthorized) } —— 少了 return，后面 next.ServeHTTP() 仍会执行

• 所有提前终止路径都必须显式 return
• 别在 next.ServeHTTP() 之后再写 http.Error()，此时 header 可能已 flush，会 panic 报 http: multiple response.WriteHeader calls
• 如果需要统一错误格式，建议封装一个 writeError(w, err) 工具函数，内部先检查 w.Header().Get("Content-Type") 是否为空再决定是否写 header

r.Body 只能读一次，日志中间件想打请求体就得缓存

标准库的 r.Body 是 io.ReadCloser，一旦被 io.ReadAll(r.Body) 或 json.NewDecoder(r.Body).Decode() 消费，下游 handler 再读就是空字节。这不是 bug，是设计使然。

调试时想看完整 body，必须手动缓存：

• 先 bodyBytes, _ := io.ReadAll(r.Body)
• 再 r.Body = io.NopCloser(bytes.NewReader(bodyBytes)) 塞回去
• 注意：生产环境慎用，大文件或高并发下易 OOM；建议只采样或只记录长度（r.ContentLength）
• 别用 r.ParseForm() 后再去读 r.Body，它内部已经读过一遍了

panic 必须在 defer 里 recover，且恢复后不能继续调用 next.ServeHTTP()

HTTP handler 里任何未捕获的 panic 都会让整个 server 进程挂掉。recover 只在 defer 中生效，而且必须在 next.ServeHTTP() 调用前注册。

错误示范：
defer func() { recover() }() —— 没拿到 panic 值，也没处理
defer func() { if r := recover(); r != nil { next.ServeHTTP(w, r) } }() —— panic 后状态已不可靠，再调用下游极可能二次 panic

• 正确姿势：在闭包内 defer 里 recover()，捕获后立即用 http.Error() 返回 500，并 return
• 别试图“修复” panic 后的请求上下文——*http.Request 和 http.ResponseWriter 可能已处于不一致状态
• 如果要用结构化日志记录 panic，确保 logger 本身不会 panic（比如异步写入、带 buffer 的 writer）

中间件真正的复杂点不在语法，而在状态流转：body 流、header 写入时机、context 生命周期、panic 后的响应完整性——这些地方一松懈，问题就藏在流量高峰里突然爆发。

终于介绍完啦！小伙伴们，这篇关于《Go语言中间件教程：HTTP请求拦截技巧》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！