Golang用slog实现结构化日志教程

本文深入解析了 Go 语言标准库 slog 的正确使用方法，重点纠正常见误区：必须用 NewTextHandler 或 NewJSONHandler 包装 io.Writer（如 os.Stdout）才能传给 slog.New()，所有结构化字段需显式构造为 slog.Attr（不可直传 map 或 struct），生产环境务必通过 ReplaceAttr 过滤敏感信息、标准化时间与源码位置格式，并强调在混用 zap/logrus 等第三方日志库时需手动透传 context 中的 traceID、userID 等关键上下文，避免日志失真或数据泄露——slog 简洁强大，但每一步配置都需精准严谨，稍有疏忽就可能在线上引发可观测性危机。

slog.New() 的 handler 参数别传错类型

直接用 slog.New() 时，第二个参数必须是实现了 slog.Handler 接口的实例，不是 io.Writer 或随便一个 struct。常见错误是传 os.Stdout 进去，结果编译报错：cannot use os.Stdout (type *os.File) as type slog.Handler。

• 正确做法：用 slog.NewTextHandler 或 slog.NewJSONHandler 包一层，再传给 slog.New()
• 开发期默认用 slog.NewTextHandler(os.Stdout, nil)；上线建议用 slog.NewJSONHandler(os.Stdout, nil) 配合日志采集工具
• 如果自定义 handler，必须实现 Handle(r slog.Record) error 和 WithAttrs(attrs []slog.Attr) slog.Handler 两个方法

日志字段要显式调用 With() 或 Log() 带 Attr

slog 不支持类似 logrus.WithField("user_id", 123).Info("login") 那种链式写法，所有结构化字段必须通过 slog.Attr 显式构造，否则会丢失上下文。

• 字段名必须是字符串字面量或 slog.String() 等辅助函数生成的 slog.Attr，不能用 map 或 struct 直接塞进去
• 推荐写法：slog.With("user_id", userID).Info("user login")，其中 slog.With 返回新 logger，不影响原 logger
• 避免在循环里反复调用 slog.With() 创建大量临时 logger 实例，高频场景可提前构建带固定字段的 logger
• 注意 slog.Int("count", n) 比 slog.String("count", strconv.Itoa(n)) 更安全——后者可能因格式错误导致字段值为空或类型错乱

生产环境必须设置 ReplaceAttr 处理敏感字段和时间格式

默认的 slog.TextHandler 和 slog.JSONHandler 会把所有字段原样输出，包括 time.Time 字段（输出为完整 struct）、调试用的 file/line，甚至可能泄露 password、token 等字段。

• 用 ReplaceAttr 配置项统一过滤/重命名/格式化字段，例如屏蔽敏感键：func(_ string, a slog.Attr) slog.Attr { if a.Key == "token" || a.Key == "password" { return slog.Attr{} }; return a }
• 强制把 time.Time 转成 ISO8601 字符串：if a.Key == slog.TimeKey { a.Value = slog.StringValue(a.Value.Time().Format("2006-01-02T15:04:05Z07:00")) }
• 默认输出的 source 字段含文件路径全量信息，线上建议截取最后两级：if a.Key == slog.SourceKey { src := a.Value.Any().(*slog.Source); a.Value = slog.StringValue(fmt.Sprintf("%s:%d", filepath.Base(src.File), src.Line)) }

与第三方库（如 zap、logrus）混用时注意 context 透传失效

如果你项目里还残留部分代码用 zap.Sugar() 或 logrus.WithContext()，而新代码用 slog，那 context.Context 里的值（比如 traceID、userID）不会自动带到 slog 日志里——slog 本身不读取 context，也不提供 LogWithContext 这类方法。

• 必须手动从 context 提取字段并塞进 slog.With()，例如：if traceID := ctx.Value("trace_id"); traceID != nil { logger = logger.With("trace_id", traceID) }
• 不要依赖中间件“全局注入” slog logger，因为每个 goroutine 的 context 不同，logger 必须按需绑定
• 如果已有大量基于 context 的日志封装，强行切 slog 可能反而增加维护成本；优先考虑统一日志入口，而非混合使用

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