如何在 Go 中实现一个支持中间件的 Web 路由

标准库的 http.ServeMux 虽然用起来方便，但一旦碰上日志、鉴权、CORS 这类“中间件”需求，就立刻露怯了——它只做静态路径映射，没办法在路由匹配前后统一注入逻辑。你要么在每个 handler 里重复写 log.Println 或者 if !auth(r) { ... }，要么就得手动嵌套包装 handler，路由表一多，代码立刻变成一团乱麻。

为什么直接用 http.ServeMux 不行

说白了，http.ServeMux 本质上就是一个路由分发器——把路径映射到 http.HandlerFunc，完了。中间件链式调用？不支持。所有需要在请求处理“之前”或“之后”统一执行的行为（比如记日志、校验身份、设置响应头），都得靠手动在每个 handler 里塞一遍，或者用丑陋的嵌套包装来凑合。结果就是：路由一多，代码重复率飙升，维护成本直线上升。

业界早已有成熟的解决方案，比如 Express.js 的 app.use()、Gin 的 Use()，它们的核心思路其实非常简洁：把中间件和最终 handler 都抽象成同一类函数，然后按顺序组合起来。

用自定义 HandlerFunc 链实现中间件

核心思路很简单：把中间件定义为 func(http.Handler) http.Handler 这种类型，然后写一个组合函数，从右往左依次包装 handler。最后注册到 http.ServeMux 的是一个被层层包裹的 http.Handler。

具体做法可以参考以下代码：

• 定义中间件类型：type Middleware func(http.Handler) http.Handler
• 写一个组合函数（注意 Go 惯例是从右往左应用）：

  func Chain(h http.Handler, m ...Middleware) http.Handler {    for i := len(m) - 1; i >= 0; i-- {        h = m[i](h)    }    return h}

• 典型中间件示例（日志）：

  func Logger(next http.Handler) http.Handler {    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {        log.Printf("%s %s", r.Method, r.URL.Path)        next.ServeHTTP(w, r)    })}

• 使用时：http.Handle("/api/", Chain(apiHandler, Logger, Auth))

路由匹配阶段如何注入中间件

标准 http.ServeMux 不支持 per-route 中间件，所以你只能自己实现路由树，或者引入轻量级第三方库（比如 gorilla/mux）。不过如果你不想增加外部依赖，一个最简方案是封装一个支持中间件的 Router 结构体。关键点包括：

• 每个路由条目（Route）保存自己的中间件切片，而不是全局共享——这样不同路由可以使用不同的中间件组合
• 匹配成功后，用 Chain(handler, route.Middlewares...) 动态组装 handler
• 注意中间件执行顺序：越靠近 handler 的越先执行（即最后注册的 middleware 最先运行）
• 一个容易踩坑的地方：不要在中间件里先调用 w.WriteHeader(401) 然后又调用 next.ServeHTTP——这会导致 panic

net/http 的 ResponseWriter 包装陷阱

很多中间件需要读取或修改响应体（比如压缩、加自定义 header），这时必须包装 http.ResponseWriter。但标准库没有提供可写的 wrapper，稍不注意就会掉进坑里：

• 直接类型断言 w.(http.Hijacker) 很可能 panic，必须先检查：if hj, ok := w.(http.Hijacker); ok { ... }
• 捕获响应体需要使用 bytes.Buffer 加自定义 ResponseWriter 实现，但要注意：一旦调用 w.WriteHeader()，header 就不可再改；一旦写入数据超过 512 字节，部分 HTTP 服务器会自动发送 header 并刷新缓存
• 推荐做法：只对 header 做无副作用操作（例如 w.Header().Set("X-Trace-ID", uuid)），复杂逻辑交给专门的中间件库（如 github.com/gorilla/handlers.CompressHandler）

经验表明，中间件真正的复杂点并不在组合逻辑本身，而在于对 ResponseWriter 和 Request 生命周期的理解——比如 r.Context() 被 cancel 后，中间件里启动的 goroutine 是否还能安全运行，这个问题很多人容易忽略。