Go / 系统课时

记录请求 ID 与访问日志

记录请求 ID 与访问日志

访问日志要能回答“哪次请求、走了什么路径、返回什么状态、耗时多久”。本篇实现一个可运行的 Go 中间件:接收或生成请求 ID,把它写入响应头和 Context,并用 slog 记录方法、路径、状态码、耗时与关联标识。

学习目标

  • 为每个请求建立稳定的 request ID,并在服务内继续传播
  • 捕获 HTTP 状态码和耗时,输出可搜索的 slog 结构化访问日志
  • 识别外部 request ID、ResponseWriter 包装与分布式追踪的边界

先建立关联标识

请求 ID 的作用是把同一次请求产生的多条日志关联起来。服务可以接受上游传入的 X-Request-ID,也可以在缺失或格式不合法时自行生成;随后应把最终采用的 ID 写回响应头,并放入请求 Context 供后续处理器使用。

请求 ID 与访问日志链路

外部传入的 ID 不能无限制信任。至少要限制长度和字符集,避免控制字符、超长值或不可搜索内容进入日志。下面的示例允许字母、数字、短横线和下划线,长度最多 64 个字符。

用中间件记录完整访问日志

主示例使用 httptest 在本地直接执行中间件,因此不需要启动端口。statusWriter 负责记住最终状态码;日志放在 next.ServeHTTP 之后记录,才能同时得到响应状态和完整处理耗时。

go
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"))
}

预期输出

text
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 一并写入结构化日志。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

记录请求 ID 与访问日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通