3. Go 标准库 net/http 深入：Handler、ServeMux、中间件模式、ResponseWriter 与 Request 详解

在构建权限审计网关时，net/http 标准库是所有 HTTP 服务的基石。本章将深入剖析其核心接口与实现机制，包括 Handler、ServeMux、中间件模式、ResponseWriter 与 Request。理解这些组件的工作原理，是后续实现审计拦截、请求溯源与响应篡改的基础。

3.1 Handler 接口：一切 HTTP 处理的起点

net/http 的核心是一个简单的接口：

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

任何实现了该接口的类型都可以作为 HTTP 处理器。Go 的 HTTP 服务器在接收到请求时，会调用处理器链中最终匹配的 ServeHTTP 方法。

3.2 ServeMux：路由分发与模式匹配

http.ServeMux 是标准库提供的默认多路复用器。它根据请求的路径（或主机+路径）将请求分发给注册的 Handler。

3.2.1 路由注册与匹配规则

3.2.2 自定义 ServeMux 与路由增强

标准库的 ServeMux 不支持路径参数（如 /users/:id）、HTTP 方法匹配或正则路由。在审计网关中，通常需要自定义路由或使用第三方库。但理解其内部实现有助于你编写更高效的中间件：

// 自定义路由结构，支持方法匹配
type MethodMux struct {
    mux map[string]http.Handler
}

func (m *MethodMux) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if handler, ok := m.mux[r.Method]; ok {
        handler.ServeHTTP(w, r)
        return
    }
    http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
}

3.3 中间件模式：请求处理链的构建

中间件模式是构建审计网关的核心设计模式。它将一个 Handler 包装在另一个 Handler 中，形成处理链。每个中间件可以执行预处理、后处理或短路请求。

3.3.1 中间件函数签名

type Middleware func(http.Handler) http.Handler

这种签名允许中间件接收一个 Handler，返回一个新的 Handler。新的 Handler 可以在调用原始 Handler 前后执行自定义逻辑。

3.3.2 链式调用与执行顺序

中间件的执行顺序遵循“洋葱模型”：

// 定义中间件
func Logger(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)
        // 后置处理
        log.Printf("Response sent")
    })
}

func Auth(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 鉴权逻辑
        if !isAuthenticated(r) {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return // 短路，不调用 next
        }
        next.ServeHTTP(w, r)
    })
}

// 链式组合
handler := Logger(Auth(finalHandler))

3.4 ResponseWriter：响应构建与拦截

http.ResponseWriter 是一个接口，用于构建 HTTP 响应。在审计网关中，经常需要包装它来捕获响应状态码、响应头和响应体。

3.4.1 ResponseWriter 接口定义

type ResponseWriter interface {
    Header() http.Header
    Write([]byte) (int, error)
    WriteHeader(statusCode int)
}

3.4.2 自定义 ResponseWriter 实现审计拦截

通过包装 ResponseWriter，可以捕获写入的响应数据：

type auditResponseWriter struct {
    http.ResponseWriter
    statusCode int
    body       bytes.Buffer
}

func (w *auditResponseWriter) WriteHeader(code int) {
    w.statusCode = code
    w.ResponseWriter.WriteHeader(code)
}

func (w *auditResponseWriter) Write(b []byte) (int, error) {
    w.body.Write(b) // 捕获响应体
    return w.ResponseWriter.Write(b)
}

// 在中间件中使用
func AuditMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        aw := &auditResponseWriter{ResponseWriter: w, statusCode: http.StatusOK}
        next.ServeHTTP(aw, r)
        // 记录审计日志：aw.statusCode, aw.body.String()
    })
}

3.5 Request：请求解析与上下文传递

*http.Request 包含了客户端请求的所有信息。在审计网关中，需要深入解析其各个字段。

3.5.1 关键字段解析

3.5.2 请求体读取与缓存

请求体 Body 是 io.ReadCloser，只能读取一次。在审计中间件中，需要先读取并缓存，再放回：

func AuditBodyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        bodyBytes, _ := io.ReadAll(r.Body)
        r.Body.Close()
        // 将原始 body 放回，供后续 handler 使用
        r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
        // 记录 bodyBytes 到审计日志
        next.ServeHTTP(w, r)
    })
}

3.6 综合架构：审计网关的请求处理流程

下图展示了基于 net/http 标准库构建的审计网关内部请求处理流程：

3.7 实战：构建最小审计中间件

综合以上知识，下面是一个完整的审计中间件示例，它记录了请求方法、路径、状态码和响应体大小：

type auditEntry struct {
    Method       string
    Path         string
    StatusCode   int
    ResponseSize int
    Duration     time.Duration
}

type auditResponseWriter struct {
    http.ResponseWriter
    statusCode int
    size       int
}

func (w *auditResponseWriter) WriteHeader(code int) {
    w.statusCode = code
    w.ResponseWriter.WriteHeader(code)
}

func (w *auditResponseWriter) Write(b []byte) (int, error) {
    n, err := w.ResponseWriter.Write(b)
    w.size += n
    return n, err
}

func AuditMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        aw := &auditResponseWriter{ResponseWriter: w, statusCode: http.StatusOK}
        next.ServeHTTP(aw, r)
        entry := auditEntry{
            Method:       r.Method,
            Path:         r.URL.Path,
            StatusCode:   aw.statusCode,
            ResponseSize: aw.size,
            Duration:     time.Since(start),
        }
        // 将 entry 写入审计日志（数据库、文件或消息队列）
        log.Printf("[AUDIT] %s %s - %d (%d bytes) in %v",
            entry.Method, entry.Path, entry.StatusCode, entry.ResponseSize, entry.Duration)
    })
}

// 使用方式
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/api/users", usersHandler)
    wrappedMux := AuditMiddleware(mux)
    http.ListenAndServe(":8080", wrappedMux)
}