3. Go HTTP 中间件原理：标准库 net/http 的 Handler 接口、HandlerFunc 与中间件链式调用、context.Context 传递

在 Go 微服务架构中，HTTP 中间件是构建可观测性、安全认证、流量治理等基础设施的核心模式。理解其底层原理，需要从标准库 net/http 的三个基石入手：Handler 接口、HandlerFunc 适配器 以及 context.Context 传递机制。本章将深入剖析这些基础组件，并揭示它们如何组合成优雅的中间件链式调用。

3.1 Handler 接口：一切 HTTP 处理的起点

net/http 包定义了最核心的接口 http.Handler，它是所有 HTTP 处理逻辑的统一抽象。

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

任何实现了 ServeHTTP 方法的类型都可以作为 HTTP 处理器。这种设计带来了极高的扩展性：

• 统一性：无论是路由、控制器还是中间件，都遵循相同的接口契约。
• 组合性：通过包装（Wrapper）模式，可以将多个 Handler 串联起来。
• 测试性：可以轻松构造 mock 对象进行单元测试。

3.2 HandlerFunc：函数到接口的适配器

为了让普通函数也能满足 Handler 接口，标准库提供了 http.HandlerFunc 类型适配器。

type HandlerFunc func(ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

这种设计模式称为适配器模式。它允许开发者用最简洁的函数签名编写处理逻辑，同时保持与 Handler 接口的完全兼容。

3.3 中间件链式调用：从包装到洋葱模型

中间件的核心模式是装饰器模式：一个中间件函数接收一个 Handler，在其前后注入逻辑，然后返回一个新的 Handler。

// 中间件类型定义
type Middleware func(http.Handler) http.Handler

// 日志中间件示例
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 前置逻辑
        log.Printf("Request: %s %s", r.Method, r.URL.Path)

        // 调用下一个处理器
        next.ServeHTTP(w, r)

        // 后置逻辑
        log.Printf("Response sent for: %s", r.URL.Path)
    })
}

// 链式组合
func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

这种链式调用形成了经典的洋葱模型：请求从外层中间件进入，逐层向内传递，到达核心处理器后，响应再逐层向外返回。

3.4 context.Context 传递：请求级数据的载体

在微服务中，每个请求都需要携带元数据：请求 ID、用户身份、超时控制、链路追踪信息等。Go 1.7 引入的 context.Context 成为跨中间件和处理器传递请求级数据的标准方式。

// 上下文键类型，避免冲突
type contextKey string

const RequestIDKey contextKey = "request_id"

// 中间件：注入 Request ID
func RequestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := uuid.New().String()
        // 将值存入 context
        ctx := context.WithValue(r.Context(), RequestIDKey, id)
        // 创建带有新 context 的请求
        r = r.WithContext(ctx)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r)
    })
}

// 处理器：读取 Request ID
func handler(w http.ResponseWriter, r *http.Request) {
    id := r.Context().Value(RequestIDKey).(string)
    w.Write([]byte("Request ID: " + id))
}

3.5 完整中间件链路示例

将上述概念整合，构建一个包含超时控制、日志记录和认证的中间件链路：

func main() {
    // 最终处理器
    finalHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        userID := r.Context().Value("user_id").(string)
        w.Write([]byte("Hello, " + userID))
    })

    // 构建中间件链
    handler := Chain(
        finalHandler,
        TimeoutMiddleware(2*time.Second),
        LoggingMiddleware,
        AuthMiddleware,
    )

    http.Handle("/api", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func TimeoutMiddleware(timeout time.Duration) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ctx, cancel := context.WithTimeout(r.Context(), timeout)
            defer cancel()
            r = r.WithContext(ctx)
            next.ServeHTTP(w, r)
        })
    }
}

func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }
        // 模拟用户验证
        ctx := context.WithValue(r.Context(), "user_id", "user-123")
        r = r.WithContext(ctx)
        next.ServeHTTP(w, r)
    })
}