Go 服务为什么该从 log.Printf 迁移到 slog：结构化字段、级别与采样边界

线上接口出了慢请求，工程师通常先搜订单号、请求 ID 或租户名。若日志还是一整串格式化文本，字段一变，检索就要靠肉眼；Go 1.21 引入的 log/slog 正好把这些信息变成可过滤的键值字段，但它并不意味着所有 log.Printf 都要一次性重写。更稳妥的做法是先固定字段和级别，再逐个替换高价值日志。

当一条请求日志里找不到真正的线索

假设接口日志长这样：

2026/08/11 15:20:41 update order=O-2719 tenant=acme cost=184ms err=timeout

人眼还能读懂，但日志平台不知道哪个片段是订单号，哪个片段是耗时。想按 tenant=acme 聚合时，应用可能还混用了 tenant_id、customer 两种叫法。问题不在文本输出本身，而在每个调用点都在临时拼装语义。

这里先别急着把全部旧代码替换掉。先选一条请求链，把请求 ID、业务动作、耗时和错误状态固定下来，再观察检索是否真的变简单。

最小改法：先把 Handler 和公共字段定住

slog 把记录生成和输出格式分开。应用侧调用 Logger，Handler 决定写成文本还是 JSON。服务端通常从 JSON Handler 起步：

package main

import (
    "log/slog"
    "os"
)

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

func recordRequest(logger *slog.Logger, requestID, tenant string, costMS int) {
    requestLogger := logger.With(
        slog.String("request_id", requestID),
        slog.String("tenant", tenant),
    )
    requestLogger.Info("order updated", slog.Int("cost_ms", costMS))
}

这段代码有两个值得保留的约束：公共字段只在请求边界绑定一次，单条事件只描述本次动作；字段名使用稳定的蛇形命名，避免同一个含义在不同包里反复改名。先运行一条成功和一条失败样本，确认日志平台能按 request_id、tenant、cost_ms 分组，再扩大范围。

级别不是装饰：它决定高峰期留下什么

slog 提供 Debug、Info、Warn、Error 等常用级别，也允许使用中间数值。生产环境把最低级别设为 Info 后，Debug 记录会被 Handler 丢弃，但调用点仍可能已经完成了昂贵的数据整理。

if logger.Enabled(ctx, slog.LevelDebug) {
    logger.DebugContext(ctx, "cache inspection",
        slog.String("key", buildCacheKey(order)),
        slog.Int("bytes", estimatePayload(order)),
    )
}

这里的检查点是：把昂贵的字段构造放到 Enabled 之后。普通字符串和整数不用过度优化，真正需要留意的是序列化大对象、拼接长文本和读取额外状态。不要因为“结构化日志更快”就默认所有日志都应该保留。

迁移时最容易踩到的三个边界

键值参数不能靠位置猜

交替参数写法很短，但键和值一旦错位，输出就会变得难以解释。频繁调用的地方可以使用 slog.String、slog.Int 等明确属性，并在测试中检查 Handler 收到的记录。

敏感值不要直接交给默认格式化

订单号、手机号和令牌的处理规则不同。可以为自定义类型实现 LogValue，把需要脱敏的字段转换成可审计但不可还原的值。日志字段一旦进入集中存储，再删通常比上线前限制更麻烦。

别把所有旧日志都升成 Info

迁移初期最常见的反效果是日志量突然上涨：原本偶尔打印的调试信息被统一改成 Info。先按故障排查价值分级，业务完成事件用 Info，异常但可恢复的分支用 Warn，真正需要值班介入的失败才用 Error。

一条可回退的渐进迁移路径

1. 先在服务入口安装 JSON Handler，保留旧包的输出，比较字段是否完整。
2. 从请求 ID、租户、业务对象 ID 这类公共字段开始，使用 With 绑定。
3. 把错误日志和关键状态变化迁移到 InfoContext 或 ErrorContext，每次改动都保留一条可检索样本。
4. 对 Debug 路径增加级别检查，压测高峰日志量和分配次数。
5. 当查询、告警和回滚都能依赖新字段后，再清理重复的旧格式化日志。

回退也很简单：Handler 是独立边界，字段调用可以保留，先切回文本 Handler 或较高的最低级别。这样回退只影响输出策略，不需要重新修改业务分支。

常见问题

一定要把 log.Printf 全部换成 slog 吗？

不需要。没有检索、聚合或级别过滤需求的启动提示可以暂时保留；优先迁移故障排查频率高、字段变化多的请求日志。

slog 的 JSON Handler 会自动接入链路追踪吗？

不会。它可以从上下文中读取并写出你提供的字段，但 trace ID 的注入仍要由调用链或中间件负责。

什么时候该增加自定义 Handler？

当现有文本或 JSON 输出无法满足脱敏、分流、采样或统一字段规则时再加。先用标准 Handler 跑通字段契约，能减少自定义实现带来的维护面。

把判断落到下一次发布检查

迁移是否值得，不看代码里出现了多少次 slog.Info，而看值班时能不能用固定字段在几秒内缩小范围。检查一次成功请求、一次超时请求和一次被级别过滤的调试事件：字段是否稳定、敏感信息是否受控、日志量是否可接受。三项都过，再继续迁移下一条请求链。