http.Handler 是日志中间件的起点，因其可统一包装处理链、捕获 panic、精确记录状态码与耗时，且避免漏记和伪造 IP 风险。
为什么 http.Handler 是日志中间件的起点
Go 的 HTTP 服务没有内置请求日志，所有日志必须手动注入到处理链中。最直接、最可控的方式是实现一个符合 http.Handler 接口的包装器——它不改变原有逻辑，只在调用 handler.ServeHTTP() 前后记录时间、状态码、路径等信息。
绕过 http.Handler（比如只在某个 http.HandleFunc 里写日志）会导致漏记、难以复用、无法捕获 panic 导致的 500 错误；用第三方框架（如 Gin 的 Logger()）虽方便，但底层仍是基于同一种包装思路。
- 必须用指针接收者或闭包保存 logger 实例，避免每次新建日志对象
- 记录开始时间要用
time.Now()，不能依赖req.Context().Deadline()，后者是截止时间，不是发起时间 - 务必在
defer中调用rw.WriteHeader()之后再记录状态码——否则rw.Status()拿不到真实值（标准ResponseWriter不暴露状态码）
如何安全获取真实客户端 IP 而不被伪造
直接读 req.RemoteAddr 在反向代理（Nginx、Cloudflare）后会得到上游服务器地址（如 127.0.0.1:32123），必须解析 X-Forwarded-For 或 X-Real-IP 头。但这些头可被客户端随意设置，不加校验等于开放 IP 伪造漏洞。
正确做法是：只信任你控制的上游代理所添加的头，并配置可信跳数。例如 Nginx 在转发时加 proxy_set_header X-Real-IP $remote_addr;，且只有一层代理，则取 X-Real-IP；若有多层，需结合 X-Forwarded-For 和 RemoteAddr 白名单判断。
立即学习“go语言免费学习笔记（深入）”；
- 不要无条件取
X-Forwarded-For的第一个值——那是最易伪造的部分 - 使用
net.ParseIP()校验提取出的 IP 是否合法，过滤空值或畸形字符串 - 生产环境应明确配置可信代理网段（如
10.0.0.0/8,172.16.0.0/12），仅对来自这些网段的请求才信任其X-Real-IP
怎样避免日志中间件影响响应性能和内存
高频请求下，字符串拼接、JSON 序列化、频繁写磁盘会显著拖慢吞吐。关键不是“要不要记”，而是“怎么记得轻”。
核心原则：日志构造尽量延迟，I/O 必须异步或缓冲。比如状态码、字节数、耗时可在 defer 中快速读取并格式化为一行字符串，然后交给独立 goroutine 写入带缓冲的 channel；避免在 handler 中调用 log.Printf() 或 json.Marshal()。
- 不要在中间件里做结构化日志（如
zerolog.Ctx(req.Context()).Info().Str("path", req.URL.Path).Int("status", status)），这会分配大量小对象 - 用
fmt.Sprintf()拼接固定格式文本比fmt.Fprintf()+bytes.Buffer更快，前提是字段少、格式稳定 - 如果用
log.SetOutput()指向文件，确保该文件以os.O_APPEND | os.O_CREATE打开，并启用行缓冲（bufio.NewWriterSize(f, 4096)）
如何捕获 panic 并记录为 500 日志
默认情况下，Go HTTP server 遇到 panic 会打印堆栈到 stderr，但不会返回 500 响应，也不会触发你的日志中间件——因为 panic 发生在 handler.ServeHTTP() 内部，中间件的 defer 已退出。
解决方案是在日志中间件内部用 defer/recover 包裹 next.ServeHTTP() 调用，并主动写响应、记录错误。注意：recover 只对当前 goroutine 有效，且必须在 defer 函数内直接调用。
func (l *loggingHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
start := time.Now()
statusCode := 200
w := &responseWriter{ResponseWriter: rw, statusCode: &statusCode}
defer func() {
if r := recover(); r != nil {
statusCode = 500
http.Error(w, http.StatusText(500), 500)
l.logger.Printf("[PANIC] %s %s %d %v %s", req.Method, req.URL.Path, statusCode, r, time.Since(start))
} else {
l.logger.Printf("%s %s %d %d %s", req.Method, req.URL.Path, statusCode, w.written, time.Since(start))
}
}()
next.ServeHTTP(w, req)
}
这里 responseWriter 是个自定义类型，实现了 WriteHeader(int) 并保存状态码；否则 panic 后无法得知本该返回什么状态。
真正难的是区分“业务 panic”和“系统 panic”。前者应转为 500 并记录；后者（如空指针解引用）建议额外上报监控系统，而不是只写日志。
