Go / 系统课时
理解 Handler 与 HandlerFunc
理解 Handler 与 HandlerFunc
本篇解决 Go HTTP 处理器为什么既能写成普通函数,也能写成结构体,并且还能被同一套中间件包裹的问题。你会从 ServeHTTP 的接口契约出发,跑通两种处理器和一个装饰器,建立统一的处理链心智模型。
学习目标
- 说明
http.Handler与ServeHTTP的最小契约 - 理解
http.HandlerFunc如何把普通函数适配为http.Handler - 能让函数处理器、结构体处理器共用同一个装饰器
Handler 的最小契约
http.Handler 只有一个方法:ServeHTTP(http.ResponseWriter, *http.Request)。任何类型只要实现这个方法,就能交给 net/http 作为请求处理器。ResponseWriter 用来写状态码、响应头和响应体,Request 保存本次请求的方法、路径、请求头与正文等信息。
服务器收到请求后,最终只关心“拿到一个 Handler,调用它的 ServeHTTP”。因此,处理器内部是函数、结构体还是组合对象,对服务器并不重要。ServeHTTP 返回时,本次处理就结束,不应再继续使用对应的 ResponseWriter。
HandlerFunc 是函数到接口的适配器
普通函数即使签名是 func(http.ResponseWriter, *http.Request),本身也没有 ServeHTTP 方法,所以不能直接满足 http.Handler。http.HandlerFunc 是一个定义过方法的函数类型:把普通函数转换成 http.HandlerFunc 后,它的 ServeHTTP 会再调用原函数。
这也是 HandleFunc 能接收普通函数的基础。结构体则可以直接定义 ServeHTTP 方法。两条路径最终都汇合到同一个 http.Handler 接口,因此装饰器只需要面向接口编程。

用同一装饰器包裹两类处理器
下面的程序分别创建函数处理器和结构体处理器,再让二者都经过 withTrace。测试使用 httptest,无需真正监听端口,运行结果是确定的。
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"strings"
)
func hello(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "hello %s", r.URL.Path)
}
type userHandler struct {
name string
}
func (h userHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "%s %s", h.name, r.URL.Path)
}
func withTrace(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 装饰器只依赖 Handler,因此不关心下游是函数还是结构体。
w.Header().Set("X-Trace", "on")
next.ServeHTTP(w, r)
})
}
func run(label string, h http.Handler, path string) {
req := httptest.NewRequest(http.MethodGet, "http://example.test"+path, nil)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
fmt.Printf("%s -> %d %s trace=%s\n",
label, rec.Code, strings.TrimSpace(rec.Body.String()),
rec.Header().Get("X-Trace"))
}
func main() {
// 普通函数转换为 HandlerFunc 后,就满足了 Handler 接口。
functionHandler := http.HandlerFunc(hello)
run("function", withTrace(functionHandler), "/hello")
run("struct", withTrace(userHandler{name: "users"}), "/users")
}预期输出
function -> 200 hello /hello trace=on
struct -> 200 users /users trace=on两次请求都出现 trace=on,说明同一个装饰器成功包裹了两类处理器。关键不在于它们最初的代码形态,而在于进入处理链前都已经是 http.Handler。
选择函数还是结构体
处理逻辑短、几乎没有依赖状态时,函数加 HandlerFunc 通常最直接;需要持有数据库、服务对象、配置或缓存等依赖时,结构体处理器更容易组织。无论采用哪种形式,中间件都应尽量接收并返回 http.Handler,这样认证、日志、限流等横切逻辑就能稳定复用,而不必为每种处理器再写一套接口。