中间件函数签名必须统一为func(http.Handler) http.Handler,接收并返回http.Handler,显式调用next.ServeHTTP(w, r),前置→调用→后置,闭包捕获配置,顺序决定执行流,recover等特殊中间件须置最外层。

中间件函数签名必须统一为 func(http.Handler) http.Handler
Go 的 http.Handler 接口是插拔基础,所有中间件必须遵守这个契约。不统一签名会导致链式调用断裂或类型错误,比如写成 func(http.ResponseWriter, *http.Request) 就无法嵌套。
实际中常见错误是把中间件写成“处理函数”而非“包装函数”,结果传给 http.Handle 时报 cannot use xxx (type func(http.ResponseWriter, *http.Request)) as type http.Handler。
- 正确模式:接收一个
http.Handler,返回一个新的http.Handler - 内部可访问原始
Handler(常命名为next),在需要时调用next.ServeHTTP(w, r) - 顺序执行逻辑:前置处理 → 调用 next → 后置处理(如日志、延迟统计)
用切片叠加中间件时注意调用顺序与闭包捕获
把多个中间件存进 []func(http.Handler) http.Handler 切片后,从左到右遍历并逐层包装,等价于手动嵌套:m1(m2(m3(handler)))。这意味着最左边的中间件最先执行前置逻辑,最后执行后置逻辑。
容易踩的坑是中间件内部闭包变量被复用。例如用 for 循环注册中间件但没拷贝当前项,导致所有中间件都引用最后一个值:
// ❌ 错误:i 在循环结束后固定为 len(ms)
for i := range ms {
handler = ms[i](handler)
}
<p>// ✅ 正确:显式绑定当前中间件
for _, m := range ms {
handler = m(handler)
}</p>
支持带参数的中间件需返回函数工厂
真实项目里中间件往往需要配置,比如 loggingWithPrefix("api") 或 timeout(30 * time.Second)。这类中间件不能直接放进中间件切片,而应设计为“返回中间件函数”的工厂函数。
参数应在工厂调用时传入,闭包捕获后用于后续每次请求处理。若把参数塞进中间件函数签名(如 func(time.Duration) func(http.Handler) http.Handler),会破坏统一接口,无法参与标准链式组装。
- 工厂函数名建议含
With或New前缀,如NewAuthMiddleware(apiKeyHeader) - 工厂内部定义并返回真正的中间件函数,确保每次调用工厂都生成独立闭包
- 避免在工厂里做耗时初始化(如读文件、建连接),除非明确是单例且线程安全
中间件顺序错位会导致逻辑失效甚至 panic
不是所有中间件都能任意排列。比如 recover 中间件必须在最外层,否则内层 panic 会绕过它;body reading 类中间件(如解析 JSON)必须在依赖原始 body 的中间件之前;gzip 响应压缩必须在所有修改响应体的中间件之后,否则压缩的是未修改前的内容。
典型冲突场景:
-
auth放在recover内侧 → 认证失败 panic 后无法被恢复 -
requestID放在logging之后 → 日志里拿不到 requestID 字段 -
cors放在auth之后 → 预检请求(OPTIONS)可能被拦截,连 auth 都没走到
调试时如果发现某中间件“没生效”,先检查它在链中的位置,比查代码逻辑更快。











