Go语言结构化日志实践教程

本文深入解析了Go语言中结构化日志的核心实践，强调slog相比fmt.Printf在生产环境中的不可替代性——它原生支持键值对结构化字段、日志层级、采样控制和灵活的Handler分发机制，能让Loki、ELK等日志系统自动解析user_id、ip等语义化字段，彻底摆脱正则硬抠字符串的脆弱方案；同时直击开发者高频踩坑点：如误用字符串拼接替代键值传参、忽略JSON格式切换、WithGroup上下文不跨goroutine传递、自定义Handler缺乏panic恢复与超时保护等，并给出可落地的初始化配置、性能权衡建议与健壮性设计原则，助你构建既清晰可查、又高可用不拖垮服务的日志基础设施。

log/slog 为什么比 fmt.Printf 更适合生产环境

因为 slog 天然支持结构化字段、层级、采样和 Handler 分发，而 fmt.Printf 输出只是字符串拼接，无法被日志系统（如 Loki、Datadog）自动解析字段。你写 slog.Info("user login", "user_id", 123, "ip", "192.168.1.5")，它就真能当 JSON 解析出 user_id 和 ip 字段；用 fmt.Printf 拼出来的字符串，得靠正则硬抠，一改格式就崩。

常见错误现象：slog.Info("user login user_id=123 ip=192.168.1.5") —— 这本质还是字符串，没用上结构化能力。

• 必须用键值对形式传参，且键必须是 string，值可以是任意类型（slog 会自动序列化）
• 避免在键里塞空格或特殊符号，比如 "user id" 不如用 "user_id"，部分后端解析器不认空格键
• 不要手动拼 JSON 字符串传给 slog，比如 slog.Info("msg", "attrs", `{"a":1}`) —— 这会让嵌套结构丢失语义，变成一个字符串字段

如何让 slog 输出 JSON 而不是默认文本格式

默认 slog 用的是 slog.TextHandler，输出可读但不可解析的文本。要对接 ELK 或云日志服务，得换 slog.JSONHandler。

实操建议：

• 初始化 logger 时显式指定 handler：logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
• 如果要用自定义时间格式，传 &slog.HandlerOptions{AddSource: true} 第二个参数，但注意：加 AddSource 会轻微拖慢性能（需 runtime.Caller），开发调试开，线上慎开
• 注意 Go 1.21+ 的 slog.JSONHandler 默认把时间转成 RFC3339 字符串，不需要额外配置；但如果你用第三方 handler（比如 github.com/samber/slog-multi），行为可能不同，得看文档

用 WithGroup 组织日志上下文时容易漏掉什么

WithGroup 是给一批日志加统一前缀字段的好方法，比如所有数据库操作都带 db 分组，但它不会自动继承到子 goroutine —— 这是最常踩的坑。

常见错误现象：主线程调了 logger = logger.WithGroup("db")，然后起 goroutine 执行查询，结果日志里没 db 字段。

• Go 的 slog.Logger 是值类型，复制后修改不影响原 logger；但 goroutine 里用的如果是旧 logger 变量，就丢了 group
• 正确做法：把带 group 的 logger 显式传进 goroutine，或用 context.Context + 自定义 value 传递（需配合 middleware 封装）
• 别滥用嵌套 group，比如 logger.WithGroup("http").WithGroup("auth").WithGroup("token") —— 过深的 group 层级会让 JSON 字段名变成 http.auth.token.xxx，部分日志平台字段名长度有限制（如 Loki 约 200 字符）

自定义 Handler 时怎么避免 panic 导致日志静默丢失

写自己的 slog.Handler（比如发到 HTTP endpoint）时，如果 handler 内部 panic，整个日志调用就静默失败，连 error 都不打 —— 因为 slog 默认不 recover。

实操建议：

• 在 Handle 方法最外层加 defer func() { if r := recover(); r != nil { /* 记录到 stderr 或 fallback 日志 */ } }()
• 网络类 handler 必须设超时，比如用 http.Client 时配 Timeout: 5 * time.Second，否则一次卡死会让后续所有日志阻塞
• 不要在 Handle 里做复杂计算或锁操作，slog 调用是同步的，卡住会影响业务逻辑执行速度

结构化日志真正难的不是怎么打，是怎么确保每条关键路径上的日志既不丢、不错、又不拖慢服务 —— 尤其在高并发或资源受限场景下，handler 的健壮性和资源控制比格式本身重要得多。

本篇关于《Go语言结构化日志实践教程》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！