中间件必须返回http.Handler，而非直接调用next.ServeHTTP()；正确做法是用闭包捕获next并转为http.HandlerFunc，以支持链式挂载、复用及兼容主流路由器。
中间件必须返回 http.Handler，不能直接调用 next.ServeHTTP()
很多人写中间件时，直接在函数体里调用 next.ServeHTTP(w, r) 就结束，结果中间件只生效一次、无法复用，还和 chi、gorilla/mux 等路由器不兼容。根本原因是：中间件不是“执行器”，而是“包装器”——它要返回一个新 http.Handler，才能被路由系统链式挂载。
常见错误写法：
func badLogging(next http.Handler) {
log.Println("before")
next.ServeHTTP(w, r) // ❌ w/r 未定义；且没返回 Handler
}
正确做法是用闭包捕获 next，并用 http.HandlerFunc 显式转换：
- 不转换会编译报错：
cannot use func literal as type http.Handler -
http.HandlerFunc是类型别名，底层实现了ServeHTTP方法，是 Go 类型系统强制的安全桥接 - 漏掉这层转换，中间件根本进不了请求链
提取用户数据这类前置逻辑，优先包装 http.HandlerFunc 而非实现 http.Handler 接口
如果你的公共逻辑轻量、无状态（比如解析 token、加载用户信息、校验权限），直接包装 http.HandlerFunc 更简洁，也更贴近实际使用场景。不需要为每个中间件都定义结构体。
立即学习“go语言免费学习笔记（深入）”；
示例：从 header 提取用户 ID 并注入到 context.Context：
func WithUser(next http.HandlerFunc) http.HandlerFunc {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userID := r.Header.Get("X-User-ID")
if userID == "" {
http.Error(w, "Missing user", http.StatusUnauthorized)
return
}
ctx := context.WithValue(r.Context(), "user_id", userID)
next(w, r.WithContext(ctx))
})
}
使用时链式调用：http.HandleFunc("/api/profile", WithUser(WithLogging(profileHandler)))
- 注意
r.WithContext()必须显式传下去，否则下游 handler 拿不到注入的值 - 别在中间件里调用
r.ParseForm()或读r.Body，body 只能读一次 - 这种写法比结构体嵌入更易测试：传入 mock request/response 即可验证行为
多个中间件叠加时，顺序决定执行流和作用域
中间件链是嵌套调用，外层先执行、内层后执行；外层后结束、内层先结束。顺序不是“谁先注册谁先跑”，而是“谁包得最外层，谁最先拦截、最后收尾”。
比如：LoggingMiddleware(AuthMiddleware(handler)) 的实际执行顺序是：
- LoggingMiddleware → 进入日志开始
- AuthMiddleware → 检查权限
- handler → 执行业务逻辑
- AuthMiddleware → 返回后继续
- LoggingMiddleware → 记录耗时并结束
所以：
- 想让日志覆盖完整请求生命周期（含 auth 耗时），就把
LoggingMiddleware放最外层 - 想让 auth 在日志前拦截非法请求，就让它包在 logging 里面
- 不要用 for 循环拼接中间件数组——闭包变量容易复用，导致并发请求互相污染
需要配置参数时，用高阶函数套一层，别用全局变量
带参中间件本质是“函数工厂”：外层接收配置，返回一个中间件函数。参数必须在初始化阶段传入，而不是每次请求都解析。
错误示范：func Auth(role string) http.Handler —— 每个角色都要新建一个中间件实例，冗余且难管理。
推荐写法（functional options）：
type AuthOption func(*authConfig)
type authConfig struct {
requiredRole string
tokenKey string
}
func WithRole(role string) AuthOption {
return func(c *authConfig) { c.requiredRole = role }
}
func Auth(opts ...AuthOption) func(http.Handler) http.Handler {
cfg := &authConfig{tokenKey: "auth_token"}
for _, opt := range opts {
opt(cfg)
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 使用 cfg.requiredRole 做校验
next.ServeHTTP(w, r)
})
}
}
- 所有配置字段必须是不可变或只读的，避免并发修改
- 闭包捕获的
cfg是每个中间件实例独享的，不会跨请求泄漏 - 如果逻辑变重（如加超时、指标统计），再考虑结构体嵌入——但起步阶段，闭包够用且不易出错
