4、Go标准库net/http：http.Handler与http.HandlerFunc、ServeMux路由、Request与ResponseWriter详解、中间件基础

Go 标准库 net/http 是构建 Web 服务的基石。理解其核心接口与类型，是掌握 REST API 契约压测的前提。本章将深入剖析 http.Handler、http.HandlerFunc、ServeMux 路由、Request 与 ResponseWriter，并建立中间件的基础认知。

核心认知： Go 的 HTTP 处理模型围绕“处理器（Handler）”展开。任何实现了 http.Handler 接口的类型都可以处理 HTTP 请求，这种简洁的设计使得组合与测试变得异常容易。

4.1 http.Handler 与 http.HandlerFunc

http.Handler 是核心接口，定义了处理 HTTP 请求的契约：

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

任何类型只要实现了 ServeHTTP 方法，就是一个合法的处理器。而 http.HandlerFunc 是一个适配器类型，允许将普通函数作为 Handler 使用：

type HandlerFunc func(ResponseWriter, *Request)

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

这种设计模式使得开发者可以灵活选择结构体或函数来定义处理逻辑。下表对比了两种方式的适用场景：

特性 结构体实现 Handler HandlerFunc 函数适配
状态管理 可携带依赖（DB、配置、日志） 需通过闭包或全局变量
代码组织 适合复杂业务逻辑 适合简单、无状态的处理
测试性 易于注入 mock 依赖 直接测试函数签名
典型场景 REST 控制器、中间件链 健康检查、静态路由
压测视角： 在契约压测中，Handler 是测试的“被测单元”。通过 httptest.NewServer 或 httptest.NewRecorder，可以直接对 Handler 发起请求并验证响应，无需启动真实服务。

4.2 ServeMux 路由

http.ServeMux 是标准库提供的 HTTP 请求多路复用器（路由器）。它根据请求的 URL 路径将请求分发到注册的 Handler。

基本用法：

mux := http.NewServeMux()
mux.HandleFunc("/api/users", listUsers)
mux.HandleFunc("/api/users/", userDetail) // 前缀匹配
mux.Handle("/health", http.HandlerFunc(healthCheck))

http.ListenAndServe(":8080", mux)

ServeMux 的匹配规则：

  • 精确匹配： 路径以 / 结尾的注册模式会匹配所有以该路径开头的请求（前缀匹配）。
  • 最长匹配： 当多个模式匹配时，选择最长的模式。
  • 重定向： 如果注册了 /api/users（无尾部斜杠），访问 /api/users/ 会 301 重定向到 /api/users。
注意： ServeMux 不支持路径参数（如 /api/users/:id）、HTTP 方法匹配或正则路由。对于 REST API 契约压测，通常需要更强大的路由库（如 gorilla/mux 或 chi），但理解 ServeMux 是掌握所有路由实现的基础。
ServeMux 路由分发流程 ServeMux 路由分发流程 HTTP 请求 ServeMux 模式匹配 Handler A Handler B Handler C 匹配规则 • 精确匹配优先 • 最长路径匹配 • /结尾为前缀匹配 • 无方法区分 • 无路径参数

4.3 Request 与 ResponseWriter 详解

每个 HTTP 请求都通过 *http.Request 和 http.ResponseWriter 传递给处理器。它们是读写 HTTP 消息的入口。

4.3.1 http.Request

Request 结构体封装了客户端发送的请求信息：

type Request struct {
    Method     string                    // GET, POST, PUT, DELETE 等
    URL        *url.URL                  // 请求 URL
    Proto      string                    // "HTTP/1.1"
    Header     Header                    // 请求头
    Body       io.ReadCloser             // 请求体
    ContentLength int64                  // 内容长度
    Host       string                    // 主机名
    RemoteAddr string                    // 客户端地址
    // ... 其他字段
}

常用操作：

  • 读取查询参数： r.URL.Query().Get("key")
  • 读取路径参数： 标准库不支持，需第三方路由或手动解析 r.URL.Path
  • 读取请求头： r.Header.Get("Content-Type")
  • 读取请求体： io.ReadAll(r.Body)，注意读取后需关闭 r.Body.Close()
  • 表单解析： r.ParseForm() 后通过 r.Form 或 r.PostForm 获取

4.3.2 http.ResponseWriter

ResponseWriter 是一个接口，用于构造 HTTP 响应：

type ResponseWriter interface {
    Header() Header          // 获取响应头映射
    Write([]byte) (int, error) // 写入响应体
    WriteHeader(int)         // 写入状态码
}

使用顺序至关重要：

  1. 先设置 Header()（如 Content-Type）
  2. 再调用 WriteHeader(statusCode)（默认 200 OK）
  3. 最后调用 Write(body) 写入响应体
压测关键点： 在契约压测中，ResponseWriter 通常由 httptest.NewRecorder 模拟。通过检查 recorder.Code、recorder.Header() 和 recorder.Body，可以精确验证响应是否符合契约。

4.4 中间件基础

中间件是一种处理 HTTP 请求的装饰器模式。它包装一个 Handler，在请求到达目标处理器之前或之后执行额外逻辑。

中间件的核心模式：

func middleware(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)

        // 后置处理：修改响应头、记录耗时等
        w.Header().Set("X-Processed-By", "middleware")
    })
}

常见的中间件职责：

中间件类型 职责 压测影响
日志记录 记录请求方法、路径、耗时 增加少量延迟，需在压测中考虑
认证鉴权 验证 JWT、API Key 等 需在请求中携带有效凭证
请求限流 基于 IP 或令牌桶限制速率 可能导致 429 响应，需设计压测策略
请求体校验 验证 Content-Type、大小限制 确保压测请求体符合规范
响应头注入 添加 CORS、安全头等 验证响应头是否包含契约字段
中间件链处理流程 中间件链处理流程 请求 日志 中间件 认证 中间件 限流 中间件 业务 Handler 响应返回路径（后置处理） 中间件链：请求依次经过每个中间件的前置逻辑 → 业务 Handler → 响应逆序经过每个中间件的后置逻辑
中间件组合： 在 Go 中，中间件通常通过 http.Handler 的嵌套组合实现。例如：http.ListenAndServe(":8080", loggingMiddleware(authMiddleware(rateLimitMiddleware(mux))))。这种模式使得每个中间件职责单一，易于测试和复用。

4.5 综合示例：构建带中间件的 REST 处理器

以下示例展示了如何组合 ServeMux、HandlerFunc 和中间件：

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "time"
)

// User 结构体
type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

// 业务处理器
func userHandler(w http.ResponseWriter, r *http.Request) {
    user := User{ID: 1, Name: "Alice"}
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(user)
}

// 日志中间件
func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
    })
}

// 认证中间件（示例）
func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("Authorization") == "" {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/api/user", userHandler)

    // 应用中间件链
    handler := loggingMiddleware(authMiddleware(mux))

    http.ListenAndServe(":8080", handler)
}
压测适配： 在契约压测中，上述代码可以直接通过 httptest.NewServer(handler) 启动测试服务器。压测脚本只需关注 /api/user 端点的请求/响应契约，中间件行为（如认证失败返回 401）也应作为契约的一部分进行验证。

通过本章的学习，你已经掌握了 Go 标准库 HTTP 处理的核心组件。这些知识是后续实现 REST API 契约压测的基础，也是理解更高级 Web 框架（如 Gin、Echo）的起点。

← 上一章 📖 返回目录 下一章 →