Go log/slog JSONHandler 如何控制时间字段格式

我在把 Go 服务日志接到只接受固定日期格式的采集器时，最容易误判的一点是：slog.JSONHandler 没有提供一个叫“时间布局”的直接选项。真正的入口是 HandlerOptions.ReplaceAttr。在这里识别根级的 time 属性，取出 time.Time 后用 Format 重建一个字符串属性，就能控制 JSON 中的时间字段；其它日志属性仍由 handler 正常处理。

先确认 JSONHandler 的默认时间输入

JSON handler 写出的是单行 JSON 对象。内置时间属性的键是 time，但它并不是普通的业务字段：当记录时间为零值时，handler 会省略它；有值时，值按 json.Marshal 处理。也就是说，单纯给 HandlerOptions 填一个 level，并不会改变时间布局。

需要改写的是 handler 看到的属性，而不是在每次 Info 调用里重复拼字符串。ReplaceAttr 收到的是已经解析过的 slog.Attr，第一个参数表示当前打开的 group 路径。根级时间通常满足 len(groups) == 0，这也是限制改写范围的关键。

用 ReplaceAttr 把时间改成字符串布局

下面的函数只改根级时间，并把时区转换、布局格式和返回属性集中在一个位置。代码中的布局必须使用 Go 的参考时间 2006-01-02 15:04:05，不能写成其它语言常见的 yyyy-MM-dd。

package main

import (
    "log/slog"
    "os"
    "time"
)

func replaceLogTime(groups []string, a slog.Attr) slog.Attr {
    // 只改 handler 的根级内置 time，避免误伤同名分组字段。
    if a.Key != slog.TimeKey || len(groups) != 0 {
        return a
    }

    t := a.Value.Time()
    // 统一使用 UTC；如果业务要求本地时间，可去掉 UTC()。
    value := t.UTC().Format("2006-01-02 15:04:05.000")
    // 返回字符串属性，JSON 中的 time 会保留为可读字符串。
    return slog.String(slog.TimeKey, value)
}

func main() {
    // ReplaceAttr 只负责改属性，Level 等其它 handler 选项仍可独立配置。
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        ReplaceAttr: replaceLogTime,
    })
    logger := slog.New(handler)
    logger.Info("request finished", slog.Int("status", 200))
}

这里不要把 a.Value.String() 当成时间格式化接口；时间值应使用 a.Value.Time() 取回 time.Time。如果想保留偏移量，把 t.UTC() 去掉，布局也可以改成 2006-01-02T15:04:05.000Z07:00。

处理分组、时区和零时间边界

格式策略通常卡在三个边界上。第一，groups 不是装饰参数：如果日志里有 slog.Group("request", slog.Time("time", t))，它的路径不为空，按上面的条件不会被当成内置时间改写。第二，日志平台若要求跨机器可比较，统一 UTC 更稳；需要展示用户所在地区时，应该在查询层转换，而不是让不同实例各写本地时间。

零时间记录本来就不会进入这个替换函数，因此不需要用 IsZero 再做一层删除判断。若你的自定义属性也使用了 time 这个键，最好换成 event_time 或加上 group，避免它和内置字段语义重叠。

把格式策略收敛成可复用函数

我更倾向于把时间布局当作日志协议的一部分，而不是散落在业务代码中的临时修补。发布前先确认采集器把 time 当字符串还是时间类型，再决定是否需要毫秒、偏移量或 Unix 秒。只要字段类型已经被下游固定，就不要在不同服务里随意切换。

如果目标是 Unix 秒，可保留默认 time，另加一个数值属性；如果必须替换内置字段，则返回 slog.Int64(slog.TimeKey, t.Unix())，但这会让消费者失去原本的时间字符串语义。多数日志检索场景中，统一 UTC 的 RFC3339 风格字符串更容易排查，也更适合人工阅读。

常见问题

为什么只设置 HandlerOptions.Level 后时间格式没变化？

Level 只控制最低日志级别，不负责序列化布局。时间改写应放在 ReplaceAttr。

ReplaceAttr 返回空 Attr 会发生什么？

返回零值 slog.Attr{} 会丢弃当前属性，适合删除字段，不适合仅修改时间格式。

应该用本地时间还是 UTC？

跨服务检索优先 UTC；面向用户展示时再按用户时区转换。关键是整个日志链路保持同一种约定。