Go 日志怎么输出结构化 JSON 并区分用户字段

Go 日志要输出结构化 JSON，核心不是把字符串拼成一行，而是让 log/slog 的 JSONHandler 统一负责编码，再用分组字段区分请求、用户和业务数据。用户字段建议放进 user 对象，令牌、密码等敏感值则在 Handler 层统一替换，避免每个调用点各写一套判断。

最稳妥的组合是：一个共享的 JSONHandler，用 request 和 user 分组表达上下文，用 ReplaceAttr 做最后一道敏感字段边界。

先把日志输出边界固定成 JSON 和分组字段

JSONHandler 默认会写出 time、level、msg 等记录字段；业务字段可以继续作为属性附加。下面的入口只创建一次，业务函数拿到同一个 logger 使用：

package main

import (
    "os"
    "log/slog"
)

func newLogger() *slog.Logger {
    // 统一从标准错误输出 JSON，便于采集器逐行读取。
    handler := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    })
    // 共享一个入口，避免不同模块自行决定文本或 JSON 格式。
    return slog.New(handler)
}

func main() {
    logger := newLogger()
    // 业务字段使用稳定的键名，不把整段用户对象直接塞进日志。
    logger.Info("订单已创建", "order_id", "o-2048", "status", "paid")
}

这里的重点是格式和字段契约分离：日志采集端只需要解析 JSON，应用端再决定哪些字段值得记录。不要把一整段拼接字符串放进 msg，否则订单号、状态等信息又退回不可检索的文本里。

用 request 和 user 分组区分业务字段

“区分用户字段”不等于给每个字段加一套随意前缀。推荐用对象分组表达语义边界，让日志查询可以写成 user.id 或 request.trace_id。WithGroup 会返回带有分组上下文的新 logger：

func logOrder(logger *slog.Logger, traceID, userID string) {
    // request 和 user 是 JSON 中的两个稳定对象。
    scoped := logger.With(
        slog.Group("request", slog.String("trace_id", traceID)),
        slog.Group("user", slog.String("id", userID)),
    )
    // 订单字段留在根记录，避免把业务对象误当成用户属性。
    scoped.Info("订单已创建", "order_id", "o-2048", "amount_cent", 12900)
}

当一组字段会伴随多条日志时，也可以使用 logger.WithGroup("user").With("id", userID)。字段名尽量表达含义：id 放在 user 下没有歧义，但订单对象下更适合用 order_id。同一条记录不要同时写根级 id 和 user.id，否则查询规则会变得含糊。

在 HandlerOptions 中处理密码、令牌等敏感字段

调用方即使约定“不记录密码”，也可能在异常分支把参数误传给日志。把最后的防线放在 HandlerOptions.ReplaceAttr 中，按属性键名替换值；这段策略不需要知道业务函数在哪里产生日志。

func newSafeLogger() *slog.Logger {
    // ReplaceAttr 统一处理最终记录中的敏感键。
    redact := func(_ []string, attr slog.Attr) slog.Attr {
        switch attr.Key {
        case "password", "token", "authorization":
            // 保留字段名，隐藏原值，方便发现误记录的位置。
            return slog.String(attr.Key, "[REDACTED]")
        default:
            return attr
        }
    }
    options := &slog.HandlerOptions{ReplaceAttr: redact}
    return slog.New(slog.NewJSONHandler(os.Stderr, options))
}

脱敏策略要覆盖实际使用的键名和嵌套分组；只检查 token 而漏掉 access_token，保护就不完整。另一方面，不要把邮箱、手机号等所有用户字段都粗暴删除：能安全用于排障的业务标识可以保留，真正敏感的值应明确替换或哈希。

字段错位时按这张检查表排查

最后做一次人工抽查：查看一条成功日志、一条错误日志和一条鉴权失败日志，分别确认字段类型、分组层级和脱敏结果。结构化日志的价值在于长期稳定，临时加一个字段之前先问清楚它属于哪个对象。

常见问题

JSONHandler 会自动把用户对象嵌套成 user 吗？

不会。只有显式使用 slog.Group("user", ...) 或 WithGroup("user")，用户字段才会形成稳定分组。

ReplaceAttr 能替换分组里的敏感字段吗？

可以，处理时会带着分组路径；策略至少要按键名覆盖真实使用的令牌、密码和授权字段。

日志里要不要保存用户手机号？

只在排障确实需要且符合业务规则时保存，优先使用内部用户编号或不可逆摘要，不要把原始手机号当作通用日志字段。