Go 结构化日志 slog Handler 并发为何需要约束

把日志封装接到 slog 后，不能再假定一次只处理一条记录。Handler 的方法允许并发调用，派生 Logger 还可能共享底层资源；只有写入器加了锁，并不能自动保护字段切片、计数器或回调状态。可行的迁移方式是让派生配置保持不可变，把确实共享的可变状态交给同一套同步机制。

官方地址：https://pkg.go.dev/log/slog。Handler 编写指南：https://github.com/golang/example/blob/master/slog-handler-guide/README.md。

迁移范围：从串行封装到共享 Handler

设想一个服务把原有日志适配器迁到 slog：API 请求和后台任务都使用它，接口层又通过 With 添加服务名、通过 WithGroup 添加请求分组。串行演示看起来正常，接入多 goroutine 后才暴露字段串用或计数不准确的问题。这是一个说明设计边界的场景，不代表已经发生或测量过某次线上事故。

这里讨论的“迁移”是封装实现方式的变化，不是某个 Go 新版本突然引入破坏性变更。官方 Handler 接口把并发管理责任交给实现者；只实现 Handle 中的一把锁，还没有回答 Enabled、WithAttrs、WithGroup 访问共享状态时怎么办。

用一张表明确共享状态

标准 JSONHandler 与 TextHandler 已有自己的输出串行化机制；同一根派生出来的实例不需要外部再包一层全方法大锁。若分别新建两个根并让它们写同一个非线程安全目标，两个根的内部锁不能当作同一把锁使用。本文的 lockedWriter 专门覆盖这种跨根共享输出的情形。

旧写法为何在派生后失效

一种常见错误是在 WithAttrs 中直接 append 到 h.attrs，再返回 h。这样，给一个请求添加字段会改变原 Logger 的后续行为；即使加锁避免了数据竞态，也没有修复父子 Logger 语义混淆。另一种错误是复制整个含 sync.Mutex 的结构体：复制后的对象可能拥有不同锁，却仍指向同一写入器。

字段切片也有相同问题：复制切片头不等于复制底层数组；复制 Attr 切片更不等于深复制 Any 中的 map、指针或业务对象。不要用“有锁”或者“做过浅拷贝”概括整条日志链的线程安全。

还有回调边界。ReplaceAttr、LogValuer 或自定义 Leveler 若读取共享业务数据，仍需各自满足并发访问约定。输出锁保护的是对应写入操作，不能顺带保护这些回调里的任意状态。

新的封装保留标准 Handler 语义

与其从头实现一套 JSON 编码器，下面的封装只统计下游 Handle 返回的错误，字段处理和分组交给标准 JSONHandler。next 在创建后不再替换；WithAttrs、WithGroup 返回新封装，但继续共享 failures。两个独立根通过同一个 sink 写入输出目标。

package main

import (
    "context"
    "fmt"
    "io"
    "log/slog"
    "os"
    "sync"
    "sync/atomic"
)

// 一个输出目标只创建一个包装实例，各根Handler共享它。
type lockedWriter struct {
    mu sync.Mutex
    dst io.Writer
}

func (w *lockedWriter) Write(p []byte) (int, error) {
    w.mu.Lock()
    defer w.mu.Unlock()
    return w.dst.Write(p)
}

// next发布后不再替换；派生Handler共享错误计数器。
type errorCountHandler struct {
    next slog.Handler
    failures *atomic.Uint64
}

func (h *errorCountHandler) Enabled(ctx context.Context, l slog.Level) bool {
    return h.next.Enabled(ctx, l)
}

func (h *errorCountHandler) Handle(ctx context.Context, r slog.Record) error {
    err := h.next.Handle(ctx, r)
    if err != nil {
        // 不在错误分支递归调用同一条日志链。
        h.failures.Add(1)
    }
    return err
}

func (h *errorCountHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    // 直接把切片所有权交给下游，不留可变字段副本。
    return &errorCountHandler{
        next: h.next.WithAttrs(attrs),
        failures: h.failures,
    }
}

func (h *errorCountHandler) WithGroup(name string) slog.Handler {
    if name == "" {
        return h
    }
    return &errorCountHandler{
        next: h.next.WithGroup(name),
        failures: h.failures,
    }
}

func main() {
    sink := &lockedWriter{dst: os.Stdout}
    failures := new(atomic.Uint64)
    makeLogger := func(service string) *slog.Logger {
        // 两个独立根Handler也共用同一个输出锁。
        next := slog.NewJSONHandler(sink, nil)
        h := &errorCountHandler{next: next, failures: failures}
        return slog.New(h).With(slog.String("service", service))
    }

    api := makeLogger("api").WithGroup("request")
    worker := makeLogger("worker")
    var wg sync.WaitGroup
    for i := 0; i 

保存为 main.go 后可用 go run main.go 观察并发记录；输出先后没有固定保证。该示例没有在本文制作过程中执行，不提供运行截图、吞吐量或竞态检测通过的结论。

lockedWriter 在一次 Write 调用期间持锁。标准 JSONHandler 每条记录以一次串行 Write 输出，因此本例可以让两个根共用这个输出边界。对于把一条记录拆成多次 Write 的其他实现，这个包装只保护每次调用，不能自动保证整条记录不交错。绕过 sink 直接写同一目标的代码也不在它的保护范围内。

封装直接转交 attrs，不再保留该切片供自身修改。它也没有修改或异步保存 Record。如果另一个封装要复制后追加属性，应了解 Record.Clone 的用途；Clone 不会替业务对象完成任意深拷贝。异步队列还需要另行设计容量、对象寿命、退出排空和丢弃策略。

回归场景应该覆盖哪些并发组合

回归不能只让很多 goroutine 对一个 Logger 调用 Info。还应包含父 Logger 与 With 派生 Logger 混用、不同 WithGroup 分支并发记录、两个独立根共用输出目标，以及下游返回写入错误时的计数行为。属性中使用固定整数或字符串，能把封装问题与业务对象的并发问题分开。

开发项目中可用 go test -race ./... 配合这些场景观察实际覆盖到的访问；竞态检测没有报告，不等于证明所有路径安全。另需断言父对象字段没有被污染、分组没有串用、记录数量符合场景约定。上述是读者的回归建议，本文发布流程未运行这些检查。

Logger 的便利方法不会把 Handle 错误返回给业务调用方，所以示例在封装内计数。计数只表示下游确实返回了多少次错误，不代表所有日志丢失情况，也不能证明落盘持久化成功；JSON字段编码失败的表现等细节还取决于下游实现。错误告警应走独立通道，避免在 Handle 错误分支递归记录到同一链。

上线迁移清单与常见问题

接入时先列出所有共享写入器、派生对象和回调；再明确哪些状态不可变，哪些共享锁或原子对象。把旧封装里会改变原对象的派生方法改为返回新实例，并让所有写入者遵守同一目标的同步约定。队列、缓冲、文件关闭和持久化要单独定义，不从“并发安全”四个字推导出来。

给 Handle 加一把锁就够了吗？不够。其他方法可能访问同一状态，业务字段值和回调也可能独立产生竞态。应按共享对象划分保护范围。

With 得到新 Logger，字段对象也复制了吗？不能这样理解。新 Logger 和任意业务 map 的深拷贝不是同一件事，日志期间仍在修改的对象需要业务层处理。

请求取消后还应该记录日志吗？Handler契约不要求随Context取消而停止记录；取消本身可能正是需要留下的事件。自定义异步实现还要另设明确的生命周期约定。