1. 中间件概念与 Go 中的实现模式

1.1 什么是中间件

在 Web 架构与分布式系统中，中间件（Middleware） 是指位于请求处理管道中的一层软件组件，它拦截进入的请求或外出的响应，在核心业务逻辑执行前后执行横切关注点（Cross-Cutting Concerns）。常见的横切关注点包括：

  • 日志记录：记录请求方法、路径、耗时、状态码。
  • 认证鉴权：校验 Token、Session、API Key。
  • 限流熔断：控制请求速率，保护下游服务。
  • 错误恢复：捕获 panic，返回统一错误响应。
  • 链路追踪：注入 Trace ID，串联调用链。
核心思想：中间件不修改业务 Handler 的内部逻辑，而是通过“包裹”的方式在 Handler 前后插入通用逻辑，实现关注点分离与复用。

1.2 Go 中的 Handler 与 HandlerFunc 接口

Go 标准库 net/http 定义了中间件实现的基础契约：

类型 签名 说明
http.Handler interface { ServeHTTP(ResponseWriter, *Request) } 接口类型，任何实现了 ServeHTTP 方法的类型都可作为 Handler。
http.HandlerFunc func(ResponseWriter, *Request) 函数适配器类型，将普通函数转换为 Handler。
func(http.Handler) http.Handler 中间件函数签名 接收一个 Handler，返回一个新的包裹后的 Handler。

中间件的本质是一个高阶函数：它接收一个 http.Handler，返回一个新的 http.Handler。新 Handler 内部先执行中间件逻辑，再调用传入的 Handler，形成嵌套包裹。

// 标准中间件函数签名
type Middleware func(next http.Handler) http.Handler

// 示例：日志中间件
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        log.Printf("[%s] %s %s", r.Method, r.URL.Path, r.RemoteAddr)
        next.ServeHTTP(w, r) // 调用下一个 Handler
        log.Printf("[%s] %s completed in %v", r.Method, r.URL.Path, time.Since(start))
    })
}

1.3 中间件链式调用原理

多个中间件可以串联成一条处理链。链式调用的核心机制是函数嵌套：每个中间件包裹下一个中间件或最终业务 Handler，形成洋葱模型（Onion Model）。

洋葱模型执行顺序：请求从最外层中间件进入，逐层向内传递，到达核心 Handler 后，响应再逐层向外返回。每一层都可以在请求进入前和响应返回后执行逻辑。

链式组合的典型实现方式有两种：

  1. 显式嵌套：middleware1(middleware2(middleware3(handler)))
  2. 链式构造器：通过切片或链表动态组合中间件。
// 链式构造器示例
func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

// 使用
finalHandler := Chain(
    myHandler,
    LoggingMiddleware,
    AuthMiddleware,
    RecoveryMiddleware,
)
中间件链式调用洋葱模型 RecoveryMiddleware（错误恢复） LoggingMiddleware（日志记录） AuthMiddleware（认证鉴权） Business Handler（业务逻辑） 请求 响应 响应逐层返回 请求从外向内逐层穿透，响应从内向外逐层返回，每层可双向拦截

1.4 中间件实现模式对比

模式 实现方式 优点 缺点
函数式嵌套 A(B(C(handler))) 简单直观，无额外依赖 嵌套过深时可读性差，顺序调整需改代码
切片链式 Chain(handler, m1, m2, m3) 顺序清晰，支持动态组合 需要构造器函数
第三方框架 Gin/Chi/Echo 的 Use() 方法 路由分组、条件中间件、上下文传递 引入外部依赖
常见陷阱：中间件中调用 next.ServeHTTP(w, r) 后，如果后续还有写入响应头的操作，可能会因 http.ResponseWriter 的隐式写入导致状态码冲突。建议在调用 next 之前完成所有响应头设置。

1.5 中间件与 Handler 的协作流程

一个完整的中间件链执行流程包含以下步骤：

  1. 请求到达：HTTP 服务器收到请求，调用最外层中间件。
  2. 前置逻辑：中间件执行请求前处理（如日志开始时间、认证检查）。
  3. 调用 next：中间件调用 next.ServeHTTP(w, r)，将控制权交给链中下一个组件。
  4. 递归传递：重复步骤 2-3，直到到达最终业务 Handler。
  5. 业务执行：Handler 处理请求，写入响应。
  6. 后置逻辑：控制权逐层返回，每个中间件执行响应后处理（如记录耗时、包装错误）。
  7. 响应返回：最外层中间件完成，响应发送给客户端。
中间件执行时序图 时间 ① 请求到达 ② 前置逻辑 ③ 调用 next ④ 业务执行 ⑤ 后置逻辑 ⑥ 响应返回

1.6 本章小结

  • 中间件 是请求处理管道中的可插拔组件，用于分离横切关注点。
  • Go 通过 http.Handler 接口和 http.HandlerFunc 函数适配器提供了中间件实现的基础。
  • 中间件链式调用遵循洋葱模型，请求逐层向内，响应逐层向外。
  • 实际工程中推荐使用切片链式构造器或第三方框架的 Use() 方法管理中间件顺序。
← 上一章 📖 返回目录 下一章 →