Go语言slog结构化日志实践方法

本文深入解析了 Go 语言中使用标准库 `slog` 实现真正结构化日志的核心要点与常见陷阱：从为何 `slog.NewJSONHandler` 会输出空对象或乱码（根源在于错误构造字段、滥用 `slog.With` 与 `slog.Group` 嵌套、忽略 Go ≥1.22 版本要求），到如何正确使用 `slog.String`/`slog.Int` 等构造函数传参、区分 `With`（上下文附加）与 `Group`（嵌套结构建模）的语义，再到适配旧日志接口、集成第三方框架及测试验证技巧——不仅帮你避开“字段丢失”“键名变 `k/v`”等典型坑，更直击生产落地难点：字段命名规范、敏感信息过滤与 tracing 上下文透传，揭示 `slog` 的设计哲学——它不负责序列化，而是把结构化能力交还给你，由你通过 Handler 精准掌控。

Go 1.21+ 的 slog 默认不输出结构化字段（比如 JSON），直接用会看到一堆未解析的键值对——这不是 bug，是设计选择：它把序列化逻辑交给你控制。

为什么 slog.NewJSONHandler 输出的是空对象或乱码？

常见现象：日志看起来像 {"time":"...","level":"INFO","msg":"hello"}，但自定义字段全丢了；或者字段名变成 ""、"k"、"v" 这种奇怪键名。

根本原因是没正确传入 context.Context 或用了错误的 slog.Group 套嵌方式，导致字段被丢弃或扁平化失败。

• 确保 handler 是用 slog.NewJSONHandler(os.Stdout, nil) 创建，而不是 slog.NewTextHandler
• 所有结构化字段必须通过 slog.String("key", "val")、slog.Int("count", 42) 等构造函数传入，不能直接写 "key", "val"（那是老式 log.Printf 风格）
• 避免在 slog.With() 后再调用 slog.With().Info() 多次嵌套 Group，容易触发字段覆盖或丢失

slog.With() 和 slog.Group() 的区别在哪？

slog.With() 是“附加字段到后续所有日志”，适合请求 ID、用户 ID 这类上下文信息；slog.Group() 是“把字段打包成一个嵌套对象”，用于建模结构化数据（如 HTTP 请求体、数据库查询参数）。

错误用法：slog.With(slog.Group("req", slog.String("method", "GET"))).Info("start") —— 这会让 req 变成顶层字段，且内部字段无法被 JSON handler 正确识别。

• 正确分组写法：slog.Info("request", slog.Group("req", slog.String("method", "GET"), slog.String("path", "/api")))
• 正确上下文写法：logger := slog.With(slog.String("trace_id", traceID)); logger.Info("db query", slog.String("sql", "SELECT * FROM users"))
• 混合使用时，Group 必须作为独立参数传给日志方法，不能塞进 With()

如何让 slog 兼容现有 log 接口或第三方库？

很多中间件（如 chi、gin）只接受 log.Logger，而 slog.Logger 不兼容。硬转不可行，得靠适配器。

Go 官方没提供转换工具，但可以用 slog.Handler + log.SetOutput 做轻量桥接：

var stdLog = log.New(slog.NewTextHandler(os.Stderr, nil), "", 0)
log.SetOutput(stdLog.Writer())

注意：这只会把标准库 log.Printf 日志转为文本格式，不带结构化字段；如果要保留结构，需自己实现 io.Writer 将 slog.Record 序列化后写入。

• 第三方框架集成优先查其文档是否已支持 slog.Handler（如 echo v5 支持 echo.WithLogger(slog.New(...))）
• 不要试图用 func() { ... }() 匿名函数包装 slog 来模拟 log.Logger，字段会丢失
• 测试中想捕获结构化输出？用 bytes.Buffer + slog.NewJSONHandler，再手动解析 JSON 字段验证

真正难的不是怎么打结构化日志，而是字段命名一致性、敏感字段过滤（比如 password）、以及和 tracing 系统（如 OpenTelemetry）的 context 透传——这些 slog 都不处理，得你自己在 Handler 层拦截 Record 做加工。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~