Go slog 结构化日志实践：从请求字段到检索定位

很多 Go 服务一开始只用 log.Println 或 fmt.Println 打日志。开发阶段看起来够用，到了线上排查接口问题时就会暴露短板：同一行里混着请求编号、路由、状态码、耗时和错误信息，想按字段过滤很困难。

log/slog 给标准库带来了结构化日志能力。它的核心价值不是“日志更漂亮”，而是把请求上下文变成稳定字段，例如 request_id、route、status、cost_ms。这些字段进入日志平台后，才能被检索、统计和告警规则复用。

目录

• 消息是什么：slog 把日志变成可检索字段
• 适用场景：哪些 Go 服务值得先接入
• 快速试用：把请求字段写进 slog
• 和旧方案对比：普通文本能看，但字段查不动
• 采用风险：字段、脱敏和日志量要先定规则
• 落地检查：上线前确认这五件事

消息是什么：slog 把日志变成可检索字段

slog 的入口很小：创建一个 Logger，给它配置 TextHandler 或 JSONHandler，然后用键值对记录业务字段。对后端服务来说，更推荐先用 JSON 输出，因为日志平台更容易解析。

下面这条日志如果是普通文本，排查时只能做模糊搜索；如果是 JSON 字段，就可以直接按 request_id=req-7f21、status=500、route=/api/order 过滤。

{
  "time": "2026-06-29T11:32:10+08:00",
  "level": "ERROR",
  "msg": "create order failed",
  "request_id": "req-7f21",
  "route": "/api/order",
  "status": 500,
  "cost_ms": 842
}

适用场景：哪些 Go 服务值得先接入

不是所有项目都要马上改日志。优先考虑这几类服务：

• 接口有多个下游依赖，排查时需要串起一次请求链路。
• 线上问题经常靠人工翻文本日志定位，效率低且容易漏字段。
• 需要按状态码、耗时、路由、租户、业务编号做统计。
• 团队已经有日志平台，希望日志字段能直接进入检索条件。

如果只是本地命令行小工具，普通文本日志仍然足够。结构化日志的收益主要来自服务端排查、监控联动和团队协作。

快速试用：把请求字段写进 slog

下面用一个最小 HTTP 服务演示。它创建 JSON 格式的 logger，给服务绑定固定字段 service=order-api，再在每次请求里记录请求编号、路由和耗时。

package main

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

func main() {
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    })

    logger := slog.New(handler).With(
        slog.String("service", "order-api"),
        slog.String("env", "dev"),
    )

    http.HandleFunc("/order", orderHandler(logger))
    logger.Info("server started", slog.String("addr", ":8080"))
    http.ListenAndServe(":8080", nil)
}

func orderHandler(logger *slog.Logger) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        requestID := r.Header.Get("X-Request-Id")
        if requestID == "" {
            requestID = "local-req"
        }

        time.Sleep(128 * time.Millisecond)
        cost := time.Since(start).Milliseconds()

        logger.InfoContext(r.Context(), "order request",
            slog.String("request_id", requestID),
            slog.String("route", r.URL.Path),
            slog.String("method", r.Method),
            slog.Int("status", http.StatusOK),
            slog.Int64("cost_ms", cost),
        )

        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`{"ok":true}`))
    }
}

本地运行后发一次请求：

go run main.go
curl -H 'X-Request-Id: req-42' http://localhost:8080/order

终端里应该能看到一行 JSON 日志，至少包含 service、request_id、route、status、cost_ms。这就是上线前最小验收点。

和旧方案对比：普通文本能看，但字段查不动

旧写法通常是把信息拼成一句话：

log.Printf("order request request_id=%s route=%s status=%d cost_ms=%d",
    requestID, r.URL.Path, http.StatusOK, cost)

这行日志人眼能读，但机器要稳定解析就麻烦了：字段顺序变了、空格多了、某个值里带特殊字符，检索规则都可能失效。slog 的键值对输出更稳定，也更适合后续统计。

采用风险：字段、脱敏和日志量要先定规则

结构化日志不是字段越多越好。真正上线前，至少要先定三条规则。

1. 字段名要稳定

同一个含义不要在不同服务里写成 requestId、request_id、rid 三种形式。建议先确定团队字段表，例如 request_id、trace_id、route、status、cost_ms。

2. 敏感信息要脱敏

不要把手机号、身份证、完整 Token、支付信息直接写进日志。确实需要定位时，可以只保留后四位、哈希摘要或内部流水号。

3. 日志量要控制

结构化日志方便检索，也更容易被滥用。高频接口不要把完整请求体、响应体和大对象全部写入 INFO 级别日志。建议只记录能定位问题的关键字段，把大对象放到调试开关或采样链路中。

落地检查：上线前确认这五件事

• 本地终端能输出合法 JSON，每行一条日志。
• 公共字段通过 Logger.With 绑定，不在每个处理函数里重复拼接。
• 请求字段包含 request_id、route、status、cost_ms。
• 日志平台能按字段过滤，不只是全文搜索。
• 敏感字段已经脱敏，日志量符合采集和存储预算。

总结一下，slog 最适合从“排查最痛的接口”开始落地。先把请求编号、路由、状态码和耗时变成稳定字段，再接入日志平台检索。等这些字段能真正帮助定位问题后，再扩展 trace、租户、业务编号和错误分类，收益会更清晰。