在 Gin 中需通过自定义 responseWriterWrapper 包装 http.ResponseWriter，重写 WriteHeader() 和 Write() 方法并加锁，在首次 WriteHeader() 时记录状态码、Write() 中累加字节数，结合 c.Set() 存储上下文，才能准确实现请求进入与响应写出的全链路埋点。
如何在 Gin 中拦截请求进入和响应写出的两个关键节点
Gin 的中间件机制天然适合做全生命周期埋点，但很多人只在 Next() 前后加日志，漏掉了响应体实际写出的时机——ResponseWriter 的 Write() 和 WriteHeader() 调用才是真正影响可观测性的环节。直接包装 http.ResponseWriter 是唯一可靠方式。
- 不要依赖
c.Writer.Status()或c.Writer.Size()在Next()后读取：它们可能尚未刷新，尤其当 handler 内部 panic 或提前 return 时值为空或不准 - 必须用自定义的
responseWriter类型嵌入原生http.ResponseWriter，重写Write()、WriteHeader()、WriteString()（可选） - 在
WriteHeader()第一次被调用时记录状态码，在Write()中累加响应体字节数，两者都需加锁（并发安全） - 将埋点上下文（如 traceID、路径、开始时间）通过
c.Set()存入 context，避免闭包捕获导致内存泄漏
为什么不能只靠 gin.Logger() 或 gin.Recovery() 做埋点
gin.Logger() 只能拿到最终状态码和耗时，但无法获取真实写出的 body 长度（它读的是 Writer.Size()，而该值在某些流式场景下为 -1）；gin.Recovery() 捕获 panic 后，响应已部分写出，此时再记日志会丢失关键指标。真正的埋点必须与 HTTP 写出动作同步。
-
gin.Logger()不感知http.Hijack()、Flush()、Pusher等底层操作，对 SSE、文件流、grpc-gateway 透传等场景完全失效 - 它默认不记录请求 body（出于性能和隐私），但某些审计场景需要采样记录 method + path + query + header size
- 若启用了 Gzip 中间件（如
gin-contrib/gzip），原始Content-Length与压缩后长度不同，必须在 gzip writer 包装链最外层拦截
一个轻量但完整的埋点中间件示例
以下代码覆盖了请求接收、路由匹配、handler 执行、响应写出四个阶段，且兼容 streaming 和 error early-return 场景：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type responseWriterWrapper struct {
http.ResponseWriter
statusCode int
written int
mu sync.RWMutex
}
func (w *responseWriterWrapper) WriteHeader(code int) {
if w.statusCode == 0 {
w.statusCode = code
}
w.ResponseWriter.WriteHeader(code)
}
func (w *responseWriterWrapper) Write(b []byte) (int, error) {
w.mu.Lock()
defer w.mu.Unlock()
n, err := w.ResponseWriter.Write(b)
w.written += n
return n, err
}
func TraceMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
traceID := c.GetHeader("X-Trace-ID")
if traceID == "" {
traceID = uuid.New().String()
}
c.Set("trace_id", traceID)
c.Set("start_time", start)
wrapper := &responseWriterWrapper{
ResponseWriter: c.Writer,
statusCode: 0,
written: 0,
}
c.Writer = wrapper
c.Next()
// 此处 statusCode 和 written 已被真实写出行为更新
status := wrapper.statusCode
if status == 0 {
status = http.StatusOK // 默认
}
size := wrapper.written
log.Printf("[trace:%s] %s %s %d %dms %dB",
traceID,
c.Request.Method,
c.Request.URL.Path,
status,
int(time.Since(start).Milliseconds()),
size)
}
}
容易被忽略的边界情况和修复建议
埋点看似简单，但在高并发或异常路径下极易失真。几个典型坑点：
立即学习“go语言免费学习笔记（深入）”；
- 如果 handler 调用
c.Abort()后又写了响应（比如在 defer 里），WriteHeader()可能未被调用，此时wrapper.statusCode仍为 0 —— 应在中间件末尾 fallback 到c.Writer.Status() - Gin 的
c.Render()在内部可能多次调用Write()，但WriteHeader()仅一次，所以统计逻辑必须分离，不能耦合 - 使用
io.Copy()直接向c.Writer写文件时，Write()可能被绕过（取决于底层实现），建议统一走c.DataFromReader()并确保 wrapper 生效 - 若集成 OpenTelemetry，不要在中间件里手动打 span，应使用
otelgin.Middleware()并配合自定义propagators提取 traceID
真正难的不是写埋点代码，而是让每个字段在所有路径下都可信。尤其是 Content-Length 和 Status，必须和 TCP 层发出的字节流严格一致，否则监控告警就失去了意义。
