Go net/http HandlerFunc 如何统一请求入口：函数适配器与中间件组合边界

写小型 HTTP 服务时，最容易混淆的是“函数能处理请求”和“它就是一个 Handler”之间的差别。http.HandlerFunc 是一个函数类型适配器：它把带有 (http.ResponseWriter, *http.Request) 签名的普通函数接到 ServeHTTP 方法上，再交给 ServeMux 统一分发。中间件则是在这个入口前后包一层，适合放请求日志、响应头和耗时检查。

先记住一条边界：HandlerFunc 负责“把函数变成 Handler”，中间件负责“包装 Handler”；两者可以组合，但不是同一层职责。

先把函数接到 ServeMux

下面的例子只保留一个业务处理函数。它没有显式声明方法，但转换成 http.HandlerFunc 后，就能作为 Handler 传给 ServeMux.Handle。

package main

import (
    "fmt"
    "net/http"
)

func helloHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintln(w, "hello, handler")
}

func main() {
    mux := http.NewServeMux()
    mux.Handle("/hello", http.HandlerFunc(helloHandler))
    _ = http.ListenAndServe(":8080", mux)
}

请求 GET /hello 时，ServeMux 找到注册的 Handler，随后调用它的 ServeHTTP。这个方法由 HandlerFunc 适配器提供，方法内部再调用原始的 helloHandler 函数。可见结果是状态码 200、响应头包含 Content-Type，响应体为 hello, handler。

Handle 和 HandleFunc 怎么选

如果手里已经是实现了 ServeHTTP 的对象，使用 mux.Handle；如果手里是普通函数，使用 mux.HandleFunc 更省一次显式转换。两条路径最终都进入 Handler 接口。

mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusNoContent)
})

这里的匿名函数仍然会被标准库适配成 HandlerFunc。不要把 HandleFunc 当成另一套路由机制，它只是针对函数签名的便利入口。

用中间件包住业务 Handler

中间件通常接收一个 http.Handler，返回另一个 http.Handler。下面让包装层负责设置响应头和记录方法、路径；业务函数仍只处理业务响应。

func withRequestLog(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("X-Request-Path", r.URL.Path)
        fmt.Printf("%s %s\n", r.Method, r.URL.Path)
        next.ServeHTTP(w, r)
    })
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", helloHandler)

    handler := withRequestLog(mux)
    _ = http.ListenAndServe(":8080", handler)
}

请求进入 withRequestLog 后，先设置 X-Request-Path 并打印日志，再调用 next.ServeHTTP 把控制权交给 helloHandler。如果把多个中间件继续套起来，最外层先执行进入逻辑，最内层先完成响应，随后按相反方向执行返回逻辑。

响应头为什么要放在 next.ServeHTTP 前

HTTP 响应一旦写出状态码或响应体，响应头通常就已经发送。把 Set 放在 next.ServeHTTP 后面，业务函数可能已经调用 WriteHeader，此时再改 X-Request-Path 往往不会出现在客户端收到的头里。记录响应耗时等“离开动作”则应放到 next.ServeHTTP 返回之后。

组合顺序决定边界

有两个包装器时，可以明确写出组合关系：

handler := withMetrics(withRequestLog(mux))

此时请求先进入 withMetrics，再进入 withRequestLog，最后到达 ServeMux。如果改写成 withRequestLog(withMetrics(mux))，进入顺序就会相反。没有“固定正确”的顺序，关键是把身份校验、日志、限流等职责放在你能解释清楚的位置。

常见误区与复查方法

• 把函数直接传给只接收 http.Handler 的参数：用 http.HandlerFunc(fn) 适配，或改用 HandleFunc。
• 在 next.ServeHTTP 后设置必须提前发送的响应头：把头部写入移到调用前。
• 包装器忘记调用 next.ServeHTTP：请求会停在中间件，业务 Handler 永远收不到请求。

本地复查时启动服务后执行 curl -i http://127.0.0.1:8080/hello，重点看响应头是否有 X-Request-Path: /hello，终端是否打印 GET /hello，以及响应体是否仍为 hello, handler。这三个结果分别证明包装层、调用链和业务 Handler 都生效。

相关问题

HandlerFunc 和 Handler 有什么关系？

Handler 是接口，要求实现 ServeHTTP；HandlerFunc 是函数类型，并为该类型提供 ServeHTTP 方法，因此函数可以被适配成 Handler。

中间件一定要返回 HandlerFunc 吗？

不一定。只要返回值实现 http.Handler 即可；返回 HandlerFunc 是因为包装逻辑本身通常就是一个请求函数。

小结

把职责拆开后，入口关系就很清楚：普通函数先由 HandlerFunc 适配，ServeMux 负责匹配路径，中间件通过 next.ServeHTTP 把请求继续传下去。真正需要留意的是响应头发送时机和包装顺序，而不是记住更多类型别名。