Go time.Time MarshalJSON 怎样保留纳秒精度

如果你把 time.Time 直接交给 encoding/json，通常不需要自己拼接纳秒字符串：标准库的 Time.MarshalJSON 会输出带引号的 RFC 3339 时间，并保留有意义的子秒精度。比如纳秒值为 123456789 时会保留九位；如果末尾是零，只会省略没有信息量的尾随零，而不是把有效精度截成毫秒。

真正需要注意的是边界：JSON 中保存的是时间瞬间、纳秒字段和时区偏移，不是 Location 名称，也不会保存进程内单调时钟读数。下面按一个具体排查场景拆开说明。

官方参考：https://pkg.go.dev/time#Time.MarshalJSON

先确认默认编码为什么能保留纳秒

time.Time 实现了 encoding/json.Marshaler。因此结构体字段使用默认 JSON 编码时，编码器会调用 MarshalJSON，得到一个 RFC 3339 字符串，而不是把内部结构直接展开成对象。

关键点有三个：time.Time 本身按纳秒精度表示时间；MarshalJSON 使用 RFC 3339 的子秒格式；结果被包在 JSON 字符串引号中。它和 t.String() 的展示格式不是同一个接口，也和 Unix 纳秒整数不是同一种契约。

用一个字段看清尾随零和九位纳秒

下面的示例同时放入完整九位纳秒和末尾带零的纳秒，观察重点是“有效数字保留、尾随零可省略”。代码只演示标准库的编码关系，不把示例输出当作截图证据。

package main

import (
    "encoding/json"
    "fmt"
    "time"
)

type Event struct {
    // 使用 time.Time 让默认 JSON 编码沿用标准 RFC 3339 语义。
    OccurredAt time.Time `json:"occurred_at"`
}

func main() {
    value := Event{
        // 这里保留九位纳秒，便于观察子秒部分的输出规则。
        OccurredAt: time.Date(2026, time.October, 31, 13, 40, 12, 123456789, time.FixedZone("CST", 8*60*60)),
    }

    data, err := json.Marshal(value)
    if err != nil {
        // 生产代码应把编码错误交给调用方，而不是吞掉它。
        panic(err)
    }
    fmt.Println(string(data))
}

{"occurred_at":"2026-10-31T13:40:12.123456789+08:00"}

如果把纳秒改成 123000000，输出中的子秒通常会变为 .123。这不是精度丢失，而是 RFC 3339 纳秒格式对无意义尾随零的压缩；只要原值中间的有效纳秒仍然存在，读取端就能还原同一个时间精度。

时区偏移会保留，但 Location 名称不会保留

序列化后的时间带有 Z 或 +08:00 这样的偏移，读取端据此解释时间瞬间。但 Location 的名字不会随着 MarshalJSON 保存；例如自定义名称 CST 和另一个相同偏移的时区，在 JSON 文本中都可能只表现为 +08:00。

这意味着接口若只需要“发生在何时”，默认格式足够；若业务还要恢复“用户选择的时区名称”，需要额外字段显式传输时区标识，不能指望从 JSON 的偏移反推原始 Location。

单调时钟、零值与 RFC 3339 错误边界

从 time.Now() 得到的值可能带有进程内单调时钟读数，这部分只服务于当前进程中的比较和相减；序列化后不会进入 JSON。跨进程传输应依赖 wall clock 与偏移，不能把单调时钟当作协议字段。

time.Time 的零值是公元 1 年的 UTC 时间。如果业务把“未设置”与真实日期区分开，建议在编码前用 IsZero 判断，并通过指针或额外状态输出 null，不要把零值误当成正常业务时间。

另外，MarshalJSON 会检查 RFC 3339 可表示范围。年份超出四位数，或时区偏移不符合 RFC 3339 时，编码会返回错误。不要在接口层直接忽略 json.Marshal 的错误。

func encodeEvent(event Event) ([]byte, error) {
    // 零值代表“没有时间”时，先把它映射成业务约定的 null。
    if event.OccurredAt.IsZero() {
        return []byte(`{"occurred_at":null}`), nil
    }

    // 让 encoding/json 负责 RFC 3339 与纳秒精度的编码和错误返回。
    return json.Marshal(event)
}

接口设计时的三项检查

排查“纳秒被截断”时，先看 JSON 文本是否只是省略了尾随零，再确认是否有自定义 DTO、字符串格式化或 Unix 毫秒转换介入。只有在这些边界都明确后，才需要自定义 MarshalJSON。

常见问题

time.Time MarshalJSON 会输出 Unix 纳秒整数吗？

不会。标准库默认输出带引号的 RFC 3339 时间字符串；如果协议要求数字时间戳，应显式设计字段和单位。

为什么输出没有九位小数？

RFC3339Nano 会省略小数部分末尾没有信息量的零。检查原始纳秒值是否真的包含那些位，不要只按字符串长度判断精度。

怎样同时保留时区名称？

把时区名称作为独立的协议字段传输。JSON 中的 +08:00 只表达偏移，无法可靠恢复原始 Location。