Go slog 结构化日志怎么落地：从 fmt.Println 到 JSON 日志的迁移路线

很多 Go 项目最开始都是几行 fmt.Println 或 log.Printf 顶着跑，排查本地问题够用，一到线上就开始难受：订单号藏在哪段文本里、用户ID有没有正常打印、同一次请求的几行日志怎么串着看，全靠肉眼翻找。log/slog 的价值不只是“标准库里自带JSON日志能力”，更重要的是让团队可以把字段规则、上下文传递和日志级别体系统一落地。

文本日志还能用，为什么团队会迁到 slog

文本日志并不是完全不能用。小服务、一次性脚本、临时跑的任务里，log.Printf("user=%d order=%s failed", uid, orderID) 的使用逻辑很直接。但线上服务数量一多，日志平台需要按指定字段检索、聚合错误量、统计接口延迟时，文本日志的短板就会暴露出来：字段名不统一、输出顺序不固定、缺少请求全链路上下文，后续手动写解析规则也很容易碎片化。

slog 把字段作为一等公民处理，日志不再是一段无结构的字符串，而是一组规则稳定的键值对。比如同样记录订单创建失败，结构化写法能让日志平台直接按 order_id、trace_id、err 精准过滤，而不是让运维人员去搜索一串模糊的文本内容。

先定字段规则，再替换原有日志调用

迁移最忌讳上来就全局批量替换。更稳妥的做法是先定一份精简的字段表，覆盖最常见的排查入口：请求标识、用户信息、业务对象、错误内容、执行耗时。字段不用一开始就追求大而全，但名称一旦确定就尽量不要改动。

字段表定好之后，再从网关入口层、核心业务层和错误返回分支开始逐步替换，不用追求短时间内把所有 Printf 全部清掉。先把高频排障路径打通，团队能立刻感知到收益，后续推进也会更顺畅。

JSONHandler 适合生产，TextHandler 适合本地

slog 常用的两个 handler 是 TextHandler 和 JSONHandler。本地开发环境可以用文本格式输出，肉眼扫读效率更高；线上日志采集场景更推荐用JSON格式，字段能被日志平台直接识别解析。

package main

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

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

    start := time.Now()
    logger.Info("create order failed",
        "trace_id", "t-20260708-001",
        "user_id", 1024,
        "order_id", "od_7788",
        "cost_ms", time.Since(start).Milliseconds(),
        "err", "stock not enough",
    )
}

这段代码输出的就是标准结构化日志，日志平台可以直接读取 trace_id 和 order_id 对应的字段值。如果你的容器日志已经由统一采集器收集，通常让应用直接输出到标准输出就足够，不用自己在业务进程里额外实现文件轮转逻辑。

上下文字段不要每行日志都手写

如果每打一行日志都手动手写 trace_id、user_id，业务代码很快就会变得冗余难维护。更合理的方式是在请求入口创建附带公共上下文的 logger 实例，再传给后续业务层使用，或者把 logger 实例放进 context 里，按照团队统一约定的规则取用。

requestLogger := logger.With(
    "trace_id", traceID,
    "user_id", userID,
)

requestLogger.Info("validate request", "path", r.URL.Path)
requestLogger.Warn("create order failed", "order_id", orderID, "err", err)

这里的重点不是写法有多精巧，而是让同一次请求产生的所有日志天然携带相同的公共上下文字段。排查线上问题时，拿到一个 trace_id 就能把接口入口、业务校验、数据库调用几个环节的日志完整串联起来。

用 WithGroup 管理模块字段

日志字段越积越多时，很容易出现命名冲突。比如订单模块有 id 字段，用户模块也有同名的 id 字段，日志平台查询时搜出来全是带 id 的结果，反而不好定位。WithGroup 可以给字段做分组归类，让整体结构更清晰。

orderLogger := logger.WithGroup("order")
orderLogger.Info("payment timeout",
    "id", "od_7788",
    "status", "pending",
)

用 JSON 格式输出时，分组后的字段会更适合日志平台按照对象层级解析。项目早期也不用急着大面积做字段分组，先在订单、支付、库存这类字段容易撞名的核心模块里试点就可以。

脱敏和成本控制要同步落地

结构化日志迁移完成后，字段检索变得更方便，也意味着敏感信息被不当暴露的概率同步提升。token、手机号、身份证号、邮箱、完整请求体这类内容，不要为了“排查方便”就原样打印到日志里。更稳妥的做法是写日志前做统一预处理：能不打印就不打印，必须留存的内容做掩码处理，只保留排查问题需要的最少信息。

成本控制也要同步考虑。Debug 级别日志、超大对象字段、循环里打印的高频日志，很容易让日志采集量突然暴涨。上线初期可以先把默认日志级别设置为 Info，针对特定模块临时打开 Debug 级别，不需要全服务长期开启 Debug。

适合小团队的轻量迁移路径

如果项目已经在线上稳定运行，不建议一口气把所有日志全量替换。可以按下面的节奏逐步推进：

• 先在新开发的功能里使用 slog，验证现有日志平台能正确解析输出的 JSON 字段。
• 把 HTTP 中间件、定时任务入口、消息消费入口这类通用流量入口统一接入 trace_id。
• 挑选 3 到 5 条团队最常排查的错误链路，替换成结构化日志。
• 统一全项目的字段命名规则，清理重复字段和含义模糊的无效字段。
• 补全通用脱敏规则和日志级别管控策略，再慢慢覆盖到更多业务模块。

这个推进节奏看起来慢一些，但是全程可控。你能直观看到每一步带来的查询效率提升，也能及时发现日志采集量超限、字段命名冲突、敏感信息泄露这类潜在隐患。

常见问题

slog 一定要输出 JSON 格式吗？

不一定。本地开发场景用 TextHandler 输出更直观，生产环境如果对接了统一日志平台，JSONHandler 通常更利于后续的检索和聚合统计。

项目已经在用 zap 或 zerolog，还需要迁到 slog 吗？

不用为了迁移而迁移。如果现有第三方日志库运行稳定、字段规范也已经跑顺，可以继续沿用。slog 更适合新项目、优先使用标准库的团队，或者希望减少第三方依赖的场景。

错误字段应该命名为 err 还是 error？

核心要求是全团队统一。很多项目习惯用 err 存储错误摘要信息，用 error_code 存储业务自定义错误码。字段名一旦定下来，就尽量不要来回修改。

Debug 日志能不能一直开着？

生产环境不建议长期全量开启。Debug 日志很容易带来不必要的采集成本，也会提升敏感字段泄露的风险，更适合短期开启、限定到指定模块，排查完问题后立刻关闭。

小结

slog 真正解决的不是“怎么把日志格式换成 JSON”，而是让 Go 项目的日志体系变得可检索、可串联、可长期治理。先统一字段规则，再对接日志 handler，后续逐步处理上下文传递、字段分组、脱敏和成本管控，这条路线比全局硬替换稳妥得多。日志一旦从零散文本变成规则稳定的键值对，线上排查就不再只能靠翻屏和猜关键词。