Go HTTP中间件本质是函数套函数，标准签名返回http.Handler或接受http.HandlerFunc；需注意类型匹配、顺序嵌套、context安全传递、连接级事件不可控及响应后必须return等核心要点。
中间件函数签名必须返回 http.Handler 或接受 http.HandlerFunc
Go 的 HTTP 中间件本质是函数套函数：外层接收原始 http.Handler，返回包装后的新 http.Handler。最常见写法是闭包形式的中间件函数，参数为 http.HandlerFunc，内部用 http.HandlerFunc 包裹逻辑并调用 next.ServeHTTP(w, r)。
错误写法是直接在中间件里写 w.Write() 后不调用 next，导致后续 handler 完全被跳过；或者忘了把 next 转成 http.Handler 就直接传给 http.ListenAndServe，编译报错 cannot use myMiddleware(...) (value of type http.Handler) as http.Handler value in argument to http.ListenAndServe —— 实际上这句报错极少出现，真正常见的是类型不匹配，比如传了函数但期望 http.Handler 接口。
- 标准签名示例：
func loggingMiddleware(next http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { log.Printf("Started %s %s", r.Method, r.URL.Path) next(w, r) log.Printf("Completed %s %s", r.Method, r.URL.Path) } } - 若需操作 response header 或状态码，必须在
next调用前或后做，但不能在next中途修改已写出的 body（HTTP/1.1 不允许重写已 flush 的响应） - 不要在中间件里 recover panic 后继续调用
next，除非你明确知道该请求还能安全继续 —— 多数情况应捕获后直接写 error response 并 return
使用 http.ServeMux 时链式注册中间件要手动嵌套
http.ServeMux 本身不支持中间件栈，必须靠手写嵌套调用实现顺序执行。比如想按「日志 → 认证 → 路由」顺序，就得写成 loggingMiddleware(authMiddleware(routingHandler))，而不是像 Gin 那样用 Use() 累加。
这种写法容易出错：顺序颠倒（比如认证放到了日志之后，但认证失败时没日志）、漏掉某一层、或嵌套过深导致可读性差。更麻烦的是，一旦某个中间件需要访问上层中间件注入的数据（如用户 ID），就得靠 context.WithValue 透传，且必须统一 key 类型（推荐用私有 struct 字段而非字符串）。
立即学习“go语言免费学习笔记（深入）”；
- 安全的 context key 示例：
type ctxKey string const userCtxKey ctxKey = "user"
- 注入方式：
ctx := context.WithValue(r.Context(), userCtxKey, userID) r = r.WithContext(ctx)
- 取值时务必判空：
if userID, ok := r.Context().Value(userCtxKey).(string); ok { ... } - 别用
map[string]interface{}存中间件数据 —— 类型丢失、无编译检查、GC 压力大
net/http 中间件无法拦截连接级事件（如 TLS 握手、连接关闭）
标准 http.Server 的中间件只作用于 HTTP 请求生命周期（从读完 request line 到写完 response body），对底层 TCP 连接、TLS 协商、keep-alive 关闭等完全不可见。这意味着你无法用中间件实现「连接限速」「客户端证书校验提前拒绝」「连接空闲超时踢出」这类功能。
如果真需要这些能力，必须换方案：
- 用
http.Server.ConnContext钩子，在连接建立时注入 context（仅能读取net.Conn元信息，不能中断握手） - 用
http.Server.TLSNextProto自定义 TLS 应用层协议分发（复杂且易出错，一般只用于 h2/cleartext） - 改用
golang.org/x/net/http2手动配置 Server，或引入fasthttp/echo等框架（它们在连接层暴露了更多钩子） - 最务实的做法：在反向代理层（如 Nginx、Envoy）处理连接级策略，Go 服务只专注 HTTP 语义层
中间件中调用 http.Redirect 或 http.Error 后必须 return
这是新手高频踩坑点。Go 没有隐式返回，http.Redirect(w, r, "/login", http.StatusFound) 只是写 header 和 body，不会终止后续代码执行。如果后面还跟着 next(w, r)，就会触发 http: multiple response.WriteHeader calls panic。
同理，http.Error 写完 500 响应后，handler 仍会继续跑 —— 若后续有 json.NewEncoder(w).Encode(...)，就直接 panic。
- 正确模式：
if !isAuthenticated(r) { http.Redirect(w, r, "/login", http.StatusFound) return // ← 必须有 } next(w, r) - 更健壮写法是封装工具函数：
func abortWithRedirect(w http.ResponseWriter, r *http.Request, url string, code int) { http.Redirect(w, r, url, code) if f, ok := w.(http.Flusher); ok { f.Flush() } }但依然要记得return - 别依赖 defer 清理：defer 在函数 return 后才执行，而 writeHeader panic 发生在第二次调用时，defer 来不及救火
