Go HTTP 中间件怎么统一记录状态码和响应大小

接口日志里只写“请求完成”，排查慢请求或错误响应时往往还缺两个最有用的字段：最终状态码和响应体实际写出的字节数。Go 的 http.Handler 已经把响应出口统一成 http.ResponseWriter，因此可以在中间件入口包一层，业务代码不用改，日志在 Handler 返回后一次性输出。

核心做法是：包装 ResponseWriter，在第一次 WriteHeader 时锁定状态码，在每次 Write 后累加返回的字节数；如果整个 Handler 没有写任何内容，再把状态按 200 处理。

先把状态码和响应大小定义成中间件契约

ResponseWriter.Write 在没有显式调用 WriteHeader 时会隐式发送 200；而显式状态通常只允许一个最终的 2xx–5xx 响应。因此中间件应把“第一次状态写入”当作最终状态，把每次写入的返回值当作真实字节数。业务 Handler 只负责生成响应，日志中间件负责观测。

用 ResponseWriter 包装器捕获 WriteHeader 与 Write

下面的包装器保留原始 Header，并把状态锁定与字节计数放在两个最关键的方法里。Write 先补齐默认状态，再调用底层写入；这样即使 Handler 只写正文，日志也能得到 200。

package main

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

// recordingWriter 只观测最终状态和成功写出的字节数。
type recordingWriter struct {
    http.ResponseWriter
    status int
    bytes  int
}

// WriteHeader 只接受第一次最终状态，避免错误日志被后续调用覆盖。
func (w *recordingWriter) WriteHeader(code int) {
    if w.status != 0 {
        return
    }
    w.status = code
    w.ResponseWriter.WriteHeader(code)
}

// Write 覆盖隐式 200，并以底层返回的 n 作为真实响应大小。
func (w *recordingWriter) Write(p []byte) (int, error) {
    if w.status == 0 {
        w.WriteHeader(http.StatusOK)
    }
    n, err := w.ResponseWriter.Write(p)
    w.bytes += n
    return n, err
}

func accessLog(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        started := time.Now()
        rw := &recordingWriter{ResponseWriter: w}
        next.ServeHTTP(rw, r)

        // Handler 没写响应时仍按 HTTP 默认语义记录 200。
        status := rw.status
        if status == 0 {
            status = http.StatusOK
        }
        log.Printf("method=%s path=%s status=%d bytes=%d elapsed=%s",
            r.Method, r.URL.Path, status, rw.bytes, time.Since(started))
    })
}

这个版本的关键是把 status 的“未写入”状态保留到返回前。若 Handler 调用 WriteHeader(204) 后直接返回，日志会得到 204 和 0 字节；若 Handler 从未触碰响应，日志则得到默认 200 和 0 字节。

把包装器接入 http.Handler 并统一输出日志

中间件的调用方向应是“外层记录器包住内层业务 Handler”。无论业务返回成功、错误还是空响应，日志出口都在同一个位置。示例中的业务函数刻意覆盖两种写法：显式错误状态和直接写正文。

func route() http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        // 明确写状态，适合错误或无正文响应。
        w.WriteHeader(http.StatusNoContent)
    })
    mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        // 直接 Write 会由 net/http 隐式使用 200。
        _, _ = w.Write([]byte("hello"))
    })
    return accessLog(mux)
}

如果把日志放在 next.ServeHTTP 之前，就只能记录请求开始时间，拿不到最终状态和响应大小。必须在 Handler 返回后读取包装器字段；同时不要在返回后继续操作 ResponseWriter，这不符合 ServeHTTP 的生命周期约束。

处理空响应、重复状态和可选接口边界

最容易遗漏的是可选接口。某些流式 Handler 会通过 http.Flusher 尽快把缓冲数据发给客户端，但自定义包装器默认只实现了 Header、Write 和 WriteHeader。如果业务需要 Flush，不能假设类型断言仍然成功；可以按需转发能力，或使用 http.NewResponseController 统一请求响应控制。

上线前可按下面的清单检查：

• Handler 只调用 Write：状态是否为 200，字节数是否等于底层返回的累计值。
• Handler 先写 404 再写正文：日志是否仍为 404，而不是被正文覆盖成 200。
• Handler 写 204 后返回：状态是否为 204，字节数是否为 0。
• 流式 Handler 调用 Flush：包装器是否显式保留了对应可选接口。

还要注意，响应大小是“写入连接的字节数”这一层面的观测值，不等于压缩前业务对象大小，也不等于客户端最终收到的网络包大小。若系统在代理层压缩，最好分别记录应用响应字节与边缘出口字节。

相关问题

为什么 status 不能只在中间件开始时设为 200？

可以用 200 作为空响应的兜底，但显式的 4xx 或 5xx 会先写入真实状态；中间件需要区分“尚未写入”和“已经写入 200”，否则会覆盖错误响应。

为什么响应大小要使用 Write 返回的 n？

底层 Writer 可能只写入部分字节并返回错误，n 才是本次实际接受的数量；用 len(p) 会把失败或部分写入也算成完整响应。

包装 ResponseWriter 会影响 SSE 或流式下载吗？

可能影响。包装器若没有实现并转发 Flusher，业务的接口断言可能失败；流式场景应明确设计可选接口兼容策略，并按协议实际测试。