Go中间件必须返回http.Handler或接收http.Handler参数，本质是包装器；正确写法是用闭包捕获依赖并返回新Handler，调用next.ServeHTTP(w, r)实现放行，漏掉将导致请求阻塞。
中间件函数必须返回 http.Handler 或接收 http.Handler 参数
Go 的 HTTP 中间件本质是“包装器”，不是独立的拦截钩子。你写一个函数，它要么接收 http.Handler 并返回新的 http.Handler，要么接收 http.HandlerFunc 并返回新的 http.HandlerFunc——否则无法接入标准库的 http.ServeMux 或 http.ListenAndServe 流程。
常见错误是直接写个普通函数，比如：
func logging() { /* ... */ }这根本没法用在 http.Handle 里。正确姿势是：
- 用闭包捕获依赖（如 logger、配置），返回
func(http.Handler) http.Handler - 内部调用
next.ServeHTTP(w, r)才算真正“放行”，漏掉这句请求就卡死了 - 别在中间件里提前
w.WriteHeader()后还调用next.ServeHTTP，会 panic：http: multiple response.WriteHeader calls
日志中间件里 r.URL.Path 和 r.RequestURI 选哪个？
r.RequestURI 是原始请求行里的字符串（含 query、可能含双斜杠或编码字符），r.URL.Path 是解析后、已解码的路径（但不包含 query）。大多数日志场景要的是用户“看到的路径”，即 r.URL.EscapedPath() 更稳妥——它保留原始编码，避免因 URL.Path 自动解码导致日志和实际请求不一致。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 如果中间件要按路径做路由判断（比如权限控制），用
r.URL.Path；它规范、可比较 - 如果只是记录访问痕迹，优先用
r.RequestURI，它最接近 wire 上的真实字节 - 注意：某些反向代理（如 nginx）可能重写
RequestURI，此时需依赖X-Original-URI等 header
如何让中间件支持配置参数（比如开关 debug 日志）？
不要把配置硬编码进函数体，而是通过闭包参数传入。Go 没有“中间件工厂”的语法糖，但可以用函数返回函数来模拟：
func WithDebugLog(enabled bool) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if enabled {
log.Printf("DEBUG: %s %s", r.Method, r.URL.Path)
}
next.ServeHTTP(w, r)
})
}
}这样你可以灵活组合：
handler := WithDebugLog(true)(WithAuth(roles)(myApp))
- 参数类型尽量用具体值（
bool、string），别用map[string]interface{}—— 丢失类型安全，后期难维护 - 如果配置项多，建议封装成结构体，再提供
NewXXXMiddleware(cfg Config)构造函数 - 避免在中间件闭包里捕获大对象（如整个数据库连接池），容易引发内存泄漏
中间件顺序错了会导致 panic: http: Handler not implemented
这个错误通常不是代码写错，而是中间件链里某个环节返回了 nil 的 http.Handler。比如你写了：
func WithRecovery(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
http.Error(w, "Internal Error", http.StatusInternalServerError)
}
}()
next.ServeHTTP(w, r) // 如果 next 是 nil，这里就 panic
})
}而调用时写成 WithRecovery(nil)，就会炸。更隐蔽的是中间件嵌套过深、条件分支漏写 return，导致某条路径没返回 handler。
- 所有中间件构造函数的输入参数，都应加
if next == nil { panic("next handler is nil") }防御 - 用
http.HandlerFunc包一层再传给中间件，比直接传nil安全得多 - 调试时在每个中间件入口打日志，看哪一层没被调用，比猜快得多
中间件不是越厚越好，每加一层都意味着一次函数调用 + 一次接口转换。高频接口里，两个中间件之间的微小延迟叠加起来，可能比 handler 本身还耗时。
