2、标准库 net/http 中间件基础：http.Handler 接口详解、http.HandlerFunc 适配器、自定义中间件函数签名

Go 标准库的 net/http 包为构建 HTTP 服务提供了最核心的抽象——http.Handler 接口。理解这个接口及其配套的适配器模式，是掌握 Go 中间件链路的基石。本节将深入剖析 http.Handler 的设计哲学、http.HandlerFunc 的适配原理，并推导出中间件函数的通用签名。

2.1 http.Handler 接口：一切处理的核心契约

http.Handler 是 Go HTTP 生态中最简洁、最强大的接口之一。它只定义了一个方法：

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

任何实现了 ServeHTTP(ResponseWriter, *Request) 方法的类型，都可以作为 HTTP 处理器。这种基于接口的组合方式，使得中间件可以无缝地包装、装饰或替换处理器。

2.2 http.HandlerFunc 适配器：函数到接口的桥梁

在实际开发中，为每个处理逻辑定义一个结构体类型往往过于繁琐。Go 标准库提供了 http.HandlerFunc 适配器，允许普通函数直接实现 http.Handler 接口：

type HandlerFunc func(ResponseWriter, *Request)

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

这种适配器模式的关键在于：HandlerFunc 是一个拥有 ServeHTTP 方法的函数类型。这使得任何签名匹配的函数都可以被当作 http.Handler 使用。

• 直接使用： http.Handle("/hello", http.HandlerFunc(helloHandler))
• 隐式转换： 当函数签名匹配时，编译器会自动进行类型转换
• 中间件基础： 中间件函数通常返回 http.Handler，内部使用 http.HandlerFunc 包装匿名函数

2.3 自定义中间件函数签名：标准模式与变体

基于 http.Handler 接口，Go 社区形成了两种主流的中间件函数签名模式：

2.3.1 标准签名：func(http.Handler) http.Handler

这是最通用、最符合 Go 接口哲学的签名。中间件接收一个 http.Handler，返回一个新的 http.Handler：

func LoggerMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 前置逻辑
        log.Printf("[%s] %s %s", r.Method, r.URL.Path, time.Now())

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

        // 后置逻辑
        log.Printf("[%s] %s completed", r.Method, r.URL.Path)
    })
}

2.3.2 带配置的签名：func(config) func(http.Handler) http.Handler

当中间件需要配置参数时，使用闭包返回标准签名：

func RateLimitMiddleware(rate int, burst int) func(http.Handler) http.Handler {
    limiter := rate.NewLimiter(rate.Limit(rate), burst)
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            if !limiter.Allow() {
                http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

2.4 中间件链路的执行流程

下图展示了三个中间件（日志、认证、限流）与最终处理器组成的洋葱模型执行流程：

2.5 中间件组合与链式调用

在实际工程中，中间件通过嵌套调用的方式组合成链。以下代码展示了如何将多个中间件串联起来：

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

// 使用示例
func main() {
    finalHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, Middleware!"))
    })

    // 从外到内：日志 → 认证 → 限流 → 业务处理器
    chainedHandler := Chain(
        finalHandler,
        LoggerMiddleware,
        AuthMiddleware,
        RateLimitMiddleware(10, 20),
    )

    http.Handle("/api", chainedHandler)
    http.ListenAndServe(":8080", nil)
}

2.6 中间件函数签名的演进与选择

随着 Go 生态的发展，中间件签名也出现了一些变体。下表对比了不同签名在实际项目中的使用情况：