中间件函数必须返回http.Handler或接收http.Handler参数；正确模式是func(next http.Handler) http.Handler，错误在于未透传handler导致链路中断。
中间件函数必须返回 http.Handler 或接受 http.Handler 参数
Go 的 http.ServeMux 本身不支持中间件链，必须手动构造组合逻辑。常见错误是写成「装饰器式」闭包但忘记透传 http.Handler，导致路由无法执行。正确模式是：中间件接收一个 http.Handler，返回一个新的 http.Handler。
- 错误写法：
func logging() { /* 没有输入 handler，无法链式调用 */ } - 正确写法：
func logging(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { log.Printf("REQ: %s %s", r.Method, r.URL.Path) next.ServeHTTP(w, r) }) } - 所有中间件都应遵循该签名：
func(http.Handler) http.Handler，否则无法嵌套
链式调用顺序 = 外层中间件先执行，内层后执行
中间件嵌套顺序直接影响执行时序。比如 logging(auth(jwt(router))) 表示：请求进来时依次执行 logging → auth → jwt → router；响应返回时逆序（router → jwt → auth → logging）。这点容易和 Express/Koa 的 next() 直觉混淆。
- 若想让 JWT 验证在 Auth 之前做，就得写成
logging(jwt(auth(router))) - 使用
http.HandlerFunc包装时，务必在内部调用next.ServeHTTP(w, r)，漏掉就等于中断链路 - 不要试图在中间件里直接
return响应而不调用next—— 这是拦截逻辑，不是跳过
避免中间件重复解析 Body 或覆盖 Header
多个中间件连续读取 r.Body（如日志、JWT 解析、表单解析）会导致后续读取为空。Go 的 http.Request.Body 是一次性流，不可重放。
- 解决方案：用
io.ReadAll(r.Body)读一次，再用bytes.NewReader()重建Body并赋值回r.Body - Header 冲突常见于 CORS 和压缩中间件：后设置的
w.Header().Set()会覆盖前面的，需统一管理或用Add()替代Set() - 若用
gzip中间件，必须确保它在链最外层（响应阶段最后执行），否则压缩内容会被其他中间件误处理
用结构体封装中间件配置更易维护
硬编码参数（如 JWT 密钥、日志级别）会让中间件难以复用。推荐用结构体定义配置，再通过方法构造中间件函数。
立即学习“go语言免费学习笔记（深入）”；
type JWTMiddleware struct {
SecretKey []byte
Issuer string
}
func (j JWTMiddleware) Handler(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r http.Request) {
// 验证逻辑使用 j.SecretKey 和 j.Issuer
next.ServeHTTP(w, r)
})
}
- 实例化：
jwtMW := &JWTMiddleware{SecretKey: []byte("mykey"), Issuer: "api"} - 链式调用：
logging(jwtMW.Handler(authMW.Handler(router))) - 比纯函数更易测试、注入 mock、区分环境配置
中间件链的真正复杂点不在写法，而在状态传递与副作用控制——比如如何把用户 ID 从 JWT 中间件安全地透传给业务 handler，又不依赖全局变量或修改原始 *http.Request 结构。这个需要结合 context.WithValue 和类型安全的 key，但那是另一个容易出错的深水区。
