Go log/slog Handler怎样给结构化日志增加自定义字段为什么结果为空或不符合预期

给 log/slog 增加自定义字段后，最容易误判的是“字段没出现”。先把现象拆成三个可计数的指标：整条日志是否产生、字段是否出现、字段是否落在预期分组。固定字段优先用 Logger.With；只有需要从 context.Context 提取请求信息时，才包装 Handler。包装器必须同时保留 Enabled、Handle、WithAttrs 和 WithGroup 的语义，否则首次调用看似正常，派生 Logger 后就可能丢字段。

官方地址：https://pkg.go.dev/log/slog

1. 先建立字段缺失的基线指标

假设库存服务要记录 service、route、request_id 和 count。这四个字段分别代表服务级属性、请求范围属性、请求关联标识和事件属性。排障时不要只看一行日志，而是固定同一条消息，按下面四个观察项记录结果：

这样记录的好处是能区分“没有进入 Handle”和“已经进入但字段位置不同”。JSONHandler 默认只接收达到配置级别的记录；例如配置为 Info 时，Debug 记录不会进入自定义 Handler。另一个常见基线偏差是 TextHandler 或默认日志写到了 stderr，而采集脚本只读取 stdout。

2. 根据 Handler 调用边界提出原因假设

log/slog 的前端是 Logger，后端是 Handler。一次日志调用先询问 Enabled，通过后才把 Record 交给 Handle。Logger.With 会调用 Handler.WithAttrs，Logger.WithGroup 会调用 Handler.WithGroup，两个方法都应该返回新的 Handler，而不是修改原对象。

因此可以提出一个明确假设：如果包装器只重写 Handle，却让嵌入的下游 Handler 自动处理派生方法，那么 With 或 WithGroup 得到的对象可能已经绕开包装器。字段第一次出现、派生 Logger 后消失，通常就是这个假设得到验证的信号。

3. 改造包装器并保留派生语义

下面的示例只从 context 提取请求标识，并把它追加到当前记录。service 使用 With，route 使用分组，count 是事件属性。代码中的注释说明了字段复制、派生 Handler 和错误返回的关键点。

package main

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

// 使用私有键类型，避免不同包用同名字符串键互相覆盖。
type requestIDKey struct{}

type requestHandler struct {
    next slog.Handler
}

func (h requestHandler) Enabled(ctx context.Context, level slog.Level) bool {
    // 先交给下游判断级别，避免为会被丢弃的记录构造字段。
    return h.next.Enabled(ctx, level)
}

func (h requestHandler) Handle(ctx context.Context, record slog.Record) error {
    id, _ := ctx.Value(requestIDKey{}).(string)
    if id != "" {
        // Record 可能共享内部属性存储，修改前先克隆以隔离副本。
        record = record.Clone()
        record.AddAttrs(slog.String("request_id", id))
    }
    // 保留下游的写出错误，让调用方仍能观察到日志通道故障。
    return h.next.Handle(ctx, record)
}

func (h requestHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    // Logger.With 产生派生 Handler，外层包装器不能在这里丢失。
    return requestHandler{next: h.next.WithAttrs(attrs)}
}

func (h requestHandler) WithGroup(name string) slog.Handler {
    // 分组语义由下游保存，但返回值仍要重新包回当前 Handler。
    return requestHandler{next: h.next.WithGroup(name)}
}

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

    // With 返回新 Logger，必须接住返回值才能保留 service。
    logger = logger.With(slog.String("service", "inventory"))
    ctx := context.WithValue(context.Background(), requestIDKey{}, "req-example")
    scoped := logger.WithGroup("request").With(slog.String("route", "/items"))
    scoped.InfoContext(ctx, "查询完成", slog.Int("count", 3))
}

把这段代码放进支持 log/slog 的 Go 工具链即可复现字段关系。这里不把示例输出冒充成线上运行结果：预期是 service 在根级，route、count 和包装器追加的 request_id 位于 request 对象内，时间、级别和消息是 JSONHandler 的基础字段。

如果把 logger.With(...) 单独写一行却继续使用旧的 logger，固定字段自然不会出现。若调用 Info 而不是 InfoContext，包装器也拿不到这次请求的 context。两者都属于调用链问题，不是 JSON 序列化问题。

4. 用固定场景复现分组与字段结果

为了比较改造前后，不需要先上复杂压测。保持同一条消息、同一个 Writer 和同一个请求 context，只切换四个场景：直接使用包装器、使用 With、使用 WithGroup、使用派生 Logger 后再写日志。每个场景记录“日志行数、字段数、字段路径”三列，结果应能直接回答字段是否丢失。

request_id 在本例中会跟随下游的 group 作用域。因此在采集系统中应按嵌套字段查询，而不能默认把它当成根级字段。不同日志平台的点号查询语法并不相同，文章这里只确认 JSON 结构，不替某个平台虚构查询规则。

5. 比较开销，并标记并发与安全边界

性能比较至少保留三个指标：ns/op、B/op 和 allocs/op。可以分别测量“无包装器”“固定字段用 With”“每条记录 Clone 并追加 request_id”三种场景，再把同一 Go 版本、同一 Handler、同一字段数量写进表头。本文不提供未经运行得到的倍数；可复现的比较方法比虚构一个“提升百分比”更可靠。

# 在文章示例所在目录执行基准测试，保留三项核心指标。
go test -bench='BenchmarkSlog' -benchmem ./...

固定服务字段适合通过 With 提前交给 Handler，内置 Handler 有机会只格式化一次。请求字段需要按事件读取时，Clone 会增加一次记录复制成本；只有在确实存在请求标识时才追加，可以避免无意义的复制。日志参数即使最后被级别过滤，普通函数参数也可能已经求值，昂贵字段应延后计算。

公共 Handler 方法可能并发调用。示例的 next 是不变引用，派生时创建新包装器；如果以后增加 map、计数器或共享缓冲区，就要为同步和所有权单独设计。日志内容还应遵守字段允许清单，不要把密码、Cookie、鉴权头或完整请求体顺手写入结构化日志。

6. 相关问题与适用选择

为什么自定义 Handler 仍没有请求字段？先确认调用的是这个 Logger，再确认使用了 Context 方法，最后检查 context 键和值类型；如果字段只在派生前出现，重点检查 WithAttrs 和 WithGroup 是否重新包回外层。

为什么字段存在却查询不到？先看 JSON 是否被放进 request 对象，再按采集平台的嵌套字段语法查询。什么时候不需要自定义 Handler？只添加服务名、组件名等固定属性时优先用 With；只有需要从 context 自动补请求元信息，或需要统一改写记录时，才值得维护包装器。

本题的关键不是把 JSON 再序列化一遍，而是保住 Handler 的四个接口约定，并用日志行数、字段数、字段路径和基准指标逐项定位。官方接口文档可复制访问：https://pkg.go.dev/log/slog。