中间件函数签名必须返回 http.Handler 而非 http.HandlerFunc，否则嵌套或多层混用时会因类型不匹配导致链路中断；正确写法是输入输出均为 http.Handler 接口，并用 http.HandlerFunc 包装业务函数以确保类型对齐。
中间件函数签名必须返回 http.Handler，不是 http.HandlerFunc
很多人写中间件时直接返回 http.HandlerFunc，看起来能跑通，但一旦嵌套多层或混用 http.Handle 和 http.HandleFunc，就会出错——因为 http.HandleFunc 内部会把函数转成 http.Handler，而你自己返回的 http.HandlerFunc 是函数类型，不是接口实例，无法被标准库的链式调用机制识别。
正确做法是统一用 http.Handler 接口作为输入和输出类型：
-
func loggingMiddleware(next http.Handler) http.Handler—— 输入输出都是接口，可无缝嵌套 - 内部用
http.HandlerFunc(func(...))包一层，再返回，确保类型对齐 - 避免写成
func loggingMiddleware(next http.HandlerFunc) http.HandlerFunc，这会切断标准库的Handler链路
http.Handle 和 http.HandleFunc 混用会导致中间件失效
你可能发现加了日志中间件，但 /hello 路由根本不打日志——大概率是因为用了 http.HandleFunc("/hello", hello)，然后又试图用 http.Handle("/", middleware(handler)) 去包装另一个路由。这两者注册到的是同一个 http.DefaultServeMux，但行为不一致：
-
http.HandleFunc会自动把函数包装成http.Handler，但只作用于该路径，不参与你手动构造的中间件链 -
http.Handle才真正接受你返回的http.Handler实例，是中间件链的入口点 - 所有需要中间件的路由，必须统一走
http.Handle+http.HandlerFunc显式转换
示例：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
立即学习“go语言免费学习笔记（深入）”；
func main() {
mux := http.NewServeMux()
mux.Handle("/hello", loggingMiddleware(authMiddleware(http.HandlerFunc(hello))))
http.ListenAndServe(":8000", mux)
}
中间件链顺序决定执行时机，next.ServeHTTP 是关键分界点
中间件里「前置逻辑」和「后置逻辑」的边界，全靠 next.ServeHTTP(w, r) 这一行。它不是“调用下一个函数”，而是触发整个后续链的执行——包括其他中间件和最终 handler。
- 在
next.ServeHTTP之前写的代码，是请求进入时执行（如鉴权、日志开始） - 在
next.ServeHTTP之后写的代码，是响应返回时执行（如记录耗时、修改 header） - 如果忘记调用
next.ServeHTTP，后续所有中间件和业务 handler 都不会执行，请求就卡死了 - 不要用
next.ServeHTTP做条件跳过，要用return提前终止，否则可能 panic 或重复写 response
真实项目中容易漏掉的上下文传递和错误处理
标准库中间件链本身不提供请求上下文透传能力。比如你在鉴权中间件里解析出用户 ID，想让下游 handler 读到，不能靠全局变量或闭包捕获——goroutine 安全性和并发隔离都不保证。
- 必须用
r = r.WithContext(context.WithValue(r.Context(), key, value))注入数据 - 下游 handler 要用
r.Context().Value(key)取，且 key 类型推荐自定义类型，避免字符串冲突 - 中间件里捕获 panic 后，不能直接
recover()然后忽略，得写w.WriteHeader(http.StatusInternalServerError)并返回错误体，否则客户端收不到响应 - 超时控制要靠
context.WithTimeout包裹整个链，而不是只包某一层中间件
最易被忽略的一点：中间件链越长，next.ServeHTTP 的调用栈越深，debug 时看堆栈容易迷失在哪一层出的问题。建议每层中间件开头打个固定前缀日志，比如 "[auth] "、"[log] "，别只依赖时间戳。
