Go / 系统课时
记录请求 ID 与访问日志
记录请求 ID 与访问日志
访问日志要能回答“哪次请求、走了什么路径、返回什么状态、耗时多久”。本篇实现一个可运行的 Go 中间件:接收或生成请求 ID,把它写入响应头和 Context,并用 slog 记录方法、路径、状态码、耗时与关联标识。
学习目标
- 为每个请求建立稳定的 request ID,并在服务内继续传播
- 捕获 HTTP 状态码和耗时,输出可搜索的
slog结构化访问日志 - 识别外部 request ID、ResponseWriter 包装与分布式追踪的边界
先建立关联标识
请求 ID 的作用是把同一次请求产生的多条日志关联起来。服务可以接受上游传入的 X-Request-ID,也可以在缺失或格式不合法时自行生成;随后应把最终采用的 ID 写回响应头,并放入请求 Context 供后续处理器使用。

外部传入的 ID 不能无限制信任。至少要限制长度和字符集,避免控制字符、超长值或不可搜索内容进入日志。下面的示例允许字母、数字、短横线和下划线,长度最多 64 个字符。
用中间件记录完整访问日志
主示例使用 httptest 在本地直接执行中间件,因此不需要启动端口。statusWriter 负责记住最终状态码;日志放在 next.ServeHTTP 之后记录,才能同时得到响应状态和完整处理耗时。
package main
import (
"context"
"crypto/rand"
"encoding/hex"
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"time"
)
type contextKey string
const requestIDKey contextKey = "request-id"
// 保留真实 ResponseWriter,同时记录首个有效状态码。
type statusWriter struct {
http.ResponseWriter
status int
wroteHeader bool
}
func (w *statusWriter) WriteHeader(code int) {
if w.wroteHeader {
return
}
w.wroteHeader = true
w.status = code
w.ResponseWriter.WriteHeader(code)
}
func (w *statusWriter) Write(p []byte) (int, error) {
if !w.wroteHeader {
w.WriteHeader(http.StatusOK)
}
return w.ResponseWriter.Write(p)
}
func validRequestID(s string) bool {
// 限制长度和字符集,避免不可控输入直接进入日志字段。
if s == "" || len(s) > 64 {
return false
}
for _, r := range s {
if (r >= 'a' && r <= 'z') ||
(r >= 'A' && r <= 'Z') ||
(r >= '0' && r <= '9') || r == '-' || r == '_' {
continue
}
return false
}
return true
}
func newRequestID() (string, error) {
var b [16]byte
if _, err := rand.Read(b[:]); err != nil {
return "", err
}
return hex.EncodeToString(b[:]), nil
}
func accessLog(logger *slog.Logger, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if !validRequestID(id) {
var err error
id, err = newRequestID()
if err != nil {
http.Error(w, "cannot create request id", http.StatusInternalServerError)
return
}
}
w.Header().Set("X-Request-ID", id)
ctx := context.WithValue(r.Context(), requestIDKey, id)
sw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
start := time.Now()
next.ServeHTTP(sw, r.WithContext(ctx))
// 在响应完成后统一记录可检索字段。
logger.Info("request_completed",
"method", r.Method,
"path", r.URL.Path,
"status", sw.status,
"duration_ms", time.Since(start).Milliseconds(),
"request_id", id,
)
})
}
func health(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNoContent)
}
func main() {
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == slog.TimeKey {
return slog.Attr{}
}
return a
},
}))
req := httptest.NewRequest(http.MethodGet, "/health", nil)
req.Header.Set("X-Request-ID", "req-123")
rec := httptest.NewRecorder()
handler := accessLog(logger, http.HandlerFunc(health))
handler.ServeHTTP(rec, req)
fmt.Printf("status=%d\n", rec.Code)
fmt.Printf("response_request_id=%s\n", rec.Header().Get("X-Request-ID"))
}预期输出
level=INFO msg=request_completed method=GET path=/health status=204 duration_ms=<DURATION_MS> request_id=req-123
status=204
response_request_id=req-123<DURATION_MS> 取决于机器和运行时调度,实际值会不同。这里主动移除了 slog 默认时间字段,避免示例输出再引入动态 <TIME>。生产环境通常应保留时间戳,并由日志采集系统统一解析。
状态码捕获有一个实现边界
基础 statusWriter 足以覆盖普通 ResponseWriter 写入,但真实服务器中的底层 writer 还可能实现 http.Flusher、http.Hijacker、http.Pusher 等可选接口。简单包装会隐藏这些能力,WebSocket、流式响应或特定框架场景可能因此失效。
如果服务需要这些接口,应使用能够透传可选接口的包装实现,或使用框架、标准库版本所提供的响应控制能力。访问日志中也不要记录完整敏感查询串、Authorization 头、Cookie 或请求体,除非经过明确脱敏。
让 request ID 真正可搜索
结构化日志字段名应保持稳定,例如固定使用 method、path、status、duration_ms 和 request_id。这样日志平台可以按字段过滤,而不是依赖脆弱的文本匹配。
当服务继续调用下游服务时,应把关联标识放入出站请求头,让下游日志沿用或建立映射。request ID 能解决应用级日志关联,但它不替代分布式追踪;跨多服务、异步任务和并行调用的系统,更适合同时采用 W3C Trace Context,并把 trace ID 一并写入结构化日志。