Go slog 结构化日志怎么接入：从 fmt 打印到可检索字段

线上接口报错时，日志里只有一行 create order failed，想查是哪个用户触发的、对应哪笔订单、下游哪个第三方接口卡慢，翻遍好几台机器的上下文都摸不到线索。Go 项目接入 log/slog 的核心价值就在这儿：把原来纯给人读的零散字符串日志，慢慢改成能被日志平台稳定检索的标准化字段。真要落地完全没必要一口气全项目改完，先从请求入口链路、错误打点、下游调用这几个核心场景切入，走起来稳得多。

为什么 Go 项目开始重视结构化日志

很多小体量 Go 项目早期都是从 log.Println、fmt.Println 或者自己简单封装个打印函数起步的。业务逻辑不复杂的时候这么写上手快还省事；等接入的接口越来越多、全链路调用层级拉得很长，纯字符串日志的毛病就全冒出来了：字段位置飘来飘去没个准，错误码有时候打了有时候漏了，用户ID直接混在大段描述文字中间，日志平台根本没法做稳定的关键词提取。

slog 的思路很直白：把单条日志拆成固定的消息文案、日志级别，再加一组键值对格式的扩展字段。Go 官方标准库直接把它定位成面向生产环境的结构化日志包，常用操作入口包括 Info、Error、LogAttrs、JSONHandler、TextHandler 这些。对普通业务开发来说，重点根本不是背全所有API，而是把平时排查问题真的用得到的字段先固定下来。

slog 解决的是哪类排查问题

结构化日志最直接能搞定三类麻烦：按指定字段检索、用链路ID串起全链路日志、按字段做指标聚合统计。比如订单接口偶发报错，旧的纯文本日志可能就只有一句中文提示，啥上下文都没有；接入 slog 之后，直接靠链路字段就能串起网关层、业务服务层、库存服务层还有数据库的所有操作日志，也能顺着错误码、用户标识维度做批量聚合统计。

哪些角色会先受益

后端开发肯定是最先尝到甜头的，排查线上问题再也不用费劲在大段文字里捞关键字；运维和SRE的工作效率也能提上来，日志平台可以自动稳定提取字段做告警和统计；产品和客服侧也能间接省不少事，比如用户跑过来说“刚才下单失败了”，研发直接输个用户ID加上时间范围就能拉出整条关联链路的日志，不用来回扯皮要信息。

不过这里要提醒一句，别脑子一热把所有业务字段全往日志里塞。字段塞得越多，单条日志体积越大，脱敏处理的工作量也陡增，后续检索速度还会被拖慢。更务实的做法是把日志字段分成三类：全链路通用的链路字段、定位问题用的核心业务字段、排查性能用的耗时指标字段，每类挑几个真正用得上的稳定字段，先覆盖最核心的几个业务接口就行。

接入 slog 前要避开的坑

第一个大坑就是字段名随手瞎写，今天叫 uid，明天图省事写成 userId，后天又改成 user_id，传到日志平台里直接分裂成三个完全独立的字段，后续统计根本合不上。第二个坑就是图方便把完整请求体、明文手机号、鉴权Token直接打出去，结构化日志检索起来比纯文本方便太多，对应的敏感信息泄露之后扩散的影响范围也大得多。

第三个坑是只换了个输出格式，内部调用逻辑半点没改。下面这种写法虽然外层用了 slog，但还是把关键信息拼成长字符串塞进去，根本没做结构化，检索价值几乎为零：

slog.Info("create order failed: user=42 order=8899")

正常的写法是把每个核心信息都做成独立的键值对字段保留，后续检索才能用得上：

slog.Error("create order failed",
    slog.String("request_id", requestID),
    slog.Int64("user_id", userID),
    slog.String("order_id", orderID),
    slog.Duration("latency", time.Since(start)),
    slog.String("err", err.Error()),
)

从一个接口开始灰度接入

最稳的接入路径，就是先挑一个平时出问题最多、调用链路清晰、涉及字段少好约定的接口，比如创建订单接口，先把入口打印、下游库存调用打点、数据库操作结果这几个点的日志都改成带 slog 结构化字段的格式。

func NewLogger() *slog.Logger {
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    })
    return slog.New(handler)
}

func CreateOrder(ctx context.Context, logger *slog.Logger, req CreateOrderRequest) error {
    start := time.Now()
    log := logger.With(
        slog.String("request_id", RequestIDFromContext(ctx)),
        slog.Int64("user_id", req.UserID),
        slog.String("order_id", req.OrderID),
    )

    log.Info("create order started")
    if err := reserveStock(ctx, req); err != nil {
        log.Error("reserve stock failed",
            slog.String("step", "reserve_stock"),
            slog.Duration("latency", time.Since(start)),
            slog.String("err", err.Error()),
        )
        return err
    }

    log.Info("create order finished",
        slog.Duration("latency", time.Since(start)),
    )
    return nil
}

这段示例代码里，logger.With 把当前整条链路通用的字段提前绑定到局部logger实例上，后面同一链路的每条日志都不用重复传入这些公共字段，省很多重复代码。等这个接口跑了几天完全稳了，再把同一套字段命名规范推广到支付、发货、售后这些其余核心业务链路上就好。

上线后看哪些指标

接入 slog 之后，不能只盯着“日志能不能正常打印输出”这点看，更值得关注的是排查问题的效率有没有实际提升，日志整体质量是不是越来越稳定。

• 错误日志里 request_id、user_id、order_id 这几个核心字段的缺失比例。
• 核心接口的全链路日志，靠 request_id 串联成功的占比。
• 单条日志的平均大小，以及全链路日志总体积的变化幅度。
• 高频出现的同类错误，能不能顺利按 step、err、status_code 几个维度做聚合统计。
• 脱敏规则有没有覆盖手机号、邮箱、Token、身份证号这些常见敏感字段。

要是这些维度的表现都没什么明显改善，只是把原来的纯文本日志换成了JSON格式，那这次迁移的实际价值就很低了。结构化日志的核心目标从来不是格式好看，而是真的能帮大家更快定位线上问题。

常见问题

slog 一定要输出 JSON 格式吗？

完全没必要强制统一。本地开发调试阶段可以直接用更易读的文本格式输出 TextHandler，线上生产环境更常用 JSONHandler，方便日志采集端直接解析字段。核心是日志里的字段要稳定统一，而不是纠结输出格式本身。

老项目能不能慢慢逐步迁移？

完全可以。先从核心接口的错误打点场景切入，先把字段规范跑顺跑通，再慢慢替换其余旧的零散日志。一上来全量替换的风险太高，出了问题很难排查，也容易漏掉字段设计上的不合理点。

所有上下文字段都要塞到日志里吗？

当然不用。优先放排查问题必用的几个核心字段就行，敏感字段要么脱敏之后再打，要么干脆不记录。日志不是数据库，别把完整请求上下文原封不动全抄进去。

slog 会不会拖慢服务性能？

任何日志打印操作都会产生资源开销。实际项目里更要控制好日志总数量、单条日志字段数、日志输出的目标存储，还有后续采集链路的性能。超高频率的热点路径上可以把日志级别调高，别把调试用的字段长期往生产环境打。

小结

Go 项目接入 slog，本质上是一次轻量的日志治理工作，不是简简单单把原来的fmt.Print换成slog的打印函数就完事了。先统一约好字段命名规则和脱敏规范，挑核心高价值接口做灰度试点，最后拿链路串联成功率、核心字段缺失率、日志总体积这几个维度做验收。这么一步步落地出来的结构化日志，才能真的帮团队少瞎翻日志、快速定位线上问题。