Go HTTP中间件本质是func(http.Handler) http.Handler函数链，需手动拼接、顺序敏感，必须接收并返回http.Handler，调用next.ServeHTTP(w,r)实现请求前/后处理。
中间件本质是函数链，不是装饰器
Go 的 HTTP 中间件没有语言级语法支持，它只是 func(http.Handler) http.Handler 类型的函数。每次调用都返回一个新的 handler，靠闭包捕获上下文。别把它想成 Python 的 @decorator 或 Express 的 app.use() 那种“注册式”模型——Go 里你得手动拼接，漏掉一层就断链。
常见错误是把中间件写成 func(http.ResponseWriter, *http.Request)，结果无法嵌套；或者忘记 next.ServeHTTP(w, r) 导致后续 handler 永远不执行。
- 必须接收并返回
http.Handler，否则无法参与链式调用 - 内部调用
next.ServeHTTP(w, r)是关键分水岭：之前是请求前处理（如日志、鉴权），之后是响应后处理（如 header 注入、耗时统计） - 顺序敏感：
logging(middleware1(middleware2(handler)))和middleware1(logging(middleware2(handler)))行为完全不同
标准库 net/http 也能写中间件，但别硬扛
用原生 http.ServeMux 写中间件可行，但很快会陷入嵌套地狱。比如要同时加日志、CORS、JWT 验证、panic 捕获，代码会变成：
http.Handle("/api", recoverHandler(
jwtAuthHandler(
corsHandler(
loggingHandler(apiHandler)
)
)
))
这种写法难调试、难复用、难测试。真正实用的方式是用 func(http.Handler) http.Handler 组合，配合类型别名或结构体封装逻辑。
立即学习“go语言免费学习笔记（深入）”；
-
http.HandlerFunc是func(http.ResponseWriter, *http.Request)的适配器，不能直接用于中间件链，需先转成http.Handler - 推荐用
func(http.Handler) http.Handler+ 匿名函数封装，避免全局变量污染 - 如果项目规模稍大，建议直接上
chi或gorilla/mux，它们内置.Use()方法，底层仍是函数链，但接口更清晰
中间件里读取 request body 容易出错
HTTP 请求体只能读一次。在中间件里调用 r.Body.Read() 或 io.ReadAll(r.Body) 后，下游 handler 再读就会得到空内容。这是最常被忽略的坑。
正确做法是用 io.NopCloser 和 bytes.NewBuffer 重放 body：
func bodyLogger(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
r.Body.Close()
r.Body = io.NopCloser(bytes.NewBuffer(body))
// 记录 body 日志...
next.ServeHTTP(w, r)
})
}
- 必须调用
r.Body.Close()，否则连接可能无法复用 - 重放 body 有内存开销，生产环境慎用，尤其对大文件上传
- 更稳妥的做法是只记录必要字段（如 JSON 的
id、action），或用httputil.DumpRequest做浅拷贝
panic 捕获中间件必须用 defer+recover，且仅限 handler 内部
Go 的 recover() 只在 defer 函数中有效，且只对当前 goroutine 生效。HTTP server 启动后，每个请求都在独立 goroutine 中运行，所以 panic 捕获中间件必须确保 defer 在 handler 执行路径内。
典型错误写法是把 recover() 放在中间件外层函数里，那样根本捕不到：
func recoverHandler(next http.Handler) http.Handler {
// ❌ 错误：这里 recover 不起作用
defer func() {
if r := recover(); r != nil {
log.Printf("panic: %v", r)
}
}()
return next // 没有包裹实际 handler 执行
}
正确写法：
func recoverHandler(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if r := recover(); r != nil {
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
log.Printf("panic recovered: %v", r)
}
}()
next.ServeHTTP(w, r)
})
}
- 必须在
http.HandlerFunc匿名函数内部做defer，保证和 handler 同 goroutine - 恢复后不要继续调用
next.ServeHTTP，否则可能重复 panic - 注意：recover 无法捕获由
os.Exit、协程 panic 或 runtime crash 引发的终止
