如何使用Golang实现路由中间件链_Golang Web中间件组合技巧_技术教程

中间件函数必须返回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 密钥、日志级别）会让中间件难以复用。推荐用结构体定义配置，再通

过方法构造中间件函数。

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，但那是另一个容易出错的深水区。