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 接口,因此装饰器只需要面向接口编程。

Handler 与 HandlerFunc 的统一处理链

用同一装饰器包裹两类处理器

下面的程序分别创建函数处理器和结构体处理器,再让二者都经过 withTrace。测试使用 httptest,无需真正监听端口,运行结果是确定的。

go
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")
}

预期输出

text
function -> 200 hello /hello trace=on
struct -> 200 users /users trace=on

两次请求都出现 trace=on,说明同一个装饰器成功包裹了两类处理器。关键不在于它们最初的代码形态,而在于进入处理链前都已经是 http.Handler。

选择函数还是结构体

处理逻辑短、几乎没有依赖状态时,函数加 HandlerFunc 通常最直接;需要持有数据库、服务对象、配置或缓存等依赖时,结构体处理器更容易组织。无论采用哪种形式,中间件都应尽量接收并返回 http.Handler,这样认证、日志、限流等横切逻辑就能稳定复用,而不必为每种处理器再写一套接口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

理解 Handler 与 HandlerFunc

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通