Go json.Unmarshal 时间字段报错的处理方案

如果接口里的时间字段让 json.Unmarshal 返回错误，先不要急着把字段改成字符串。最常见的原因有两类：JSON 里的值是字符串，但格式不符合 time.Time 默认接受的 RFC3339；或者 JSON 值的类型与结构体字段不一致。前者要调整外部时间契约或增加解析适配，后者要修正字段类型，不能用同一个补丁混过去。

这篇只讨论时间格式与字段类型。默认模型保留 time.Time，固定的本地格式通过自定义类型或中间结构转换，空值和可选字段单独处理。

先从错误定位格式还是类型

先把输入时间、结构体字段和错误文本放在一起看。比如字段是 time.Time，输入是 "2026-10-18 09:30:00"，通常是格式问题；如果输入是数字、数组或对象，而字段仍是 time.Time，则还涉及 JSON 类型不匹配。

time.Time 实现了 JSON 解码接口，它要求时间值是带引号的 RFC3339 字符串。也就是说，2026-10-18T09:30:00+08:00 与 2026-10-18T09:30:00Z 属于更合适的输入；2026-10-18 09:30:00 少了 RFC3339 的日期时间分隔符，直接解码就可能失败。

如果错误指向 cannot unmarshal number into Go struct field 一类内容，优先确认 JSON 的值类型和 Go 字段类型；如果错误指向时间解析，优先确认布局、时区和引号。先分层，后决定是否写自定义代码。

接口允许 RFC3339 时直接保留 time.Time

当接口契约可以调整，最小方案是保持结构体字段为 time.Time，让调用方发送 RFC3339 字符串。这样领域模型拿到的就是可比较、可格式化的时间值，不必让业务层到处记住字符串布局。

package timedecode

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

type Event struct {
    Name      string    `json:"name"`
    StartedAt time.Time `json:"started_at"`
}

func DecodeEvent(data []byte) (Event, error) {
    var event Event
    // 让标准库按 time.Time 的 RFC3339 约定解析时间字段。
    if err := json.Unmarshal(data, &event); err != nil {
        return Event{}, fmt.Errorf("解码事件失败: %w", err)
    }
    return event, nil
}

这一版的接口约束很清楚：时间必须是 JSON 字符串，内容按 RFC3339 表示。错误要向上包装上下文，但不要在这里伪造一个默认时间掩盖输入问题。对于服务端接口，最好在接口文档中直接写出时间格式，而不是只写“日期时间”。

固定为本地格式时增加适配层

如果外部系统只能发送 2026-10-18 09:30:00 这样的本地格式，就不要让领域结构体承担多个外部协议。可以定义一个只负责解码的时间类型，在 UnmarshalJSON 中去掉 JSON 引号并按明确布局解析，成功后再保存为 time.Time。

package timedecode

import (
    "bytes"
    "fmt"
    "time"
)

type LocalTime struct {
    time.Time
}

func (t *LocalTime) UnmarshalJSON(data []byte) error {
    // 先处理 null 和空字符串，避免把可选字段误报成布局错误。
    value := bytes.Trim(data, "\"")
    if bytes.Equal(value, []byte("null")) || len(value) == 0 {
        t.Time = time.Time{}
        return nil
    }

    parsed, err := time.ParseInLocation("2006-01-02 15:04:05", string(value), time.Local)
    if err != nil {
        return fmt.Errorf("本地时间格式错误 %q: %w", string(value), err)
    }
    t.Time = parsed
    return nil
}

这里的布局字符串不是“格式提示”，而是解析契约。示例把没有时区的值解释为当前进程的 time.Local；如果业务实际约定固定时区，应把它改成明确的 *time.Location，不要让部署机器的时区决定同一字符串代表的时刻。

对外输出时还要考虑 MarshalJSON。如果输入格式只是上游遗留协议，内部可以用 time.Time，输出则按接口约定统一格式；不要只实现输入而让同一个类型的输出悄悄变成另一套格式。

用中间结构隔离多种外部输入

当字段格式复杂、需要保留原始值，或者同一个接口在迁移期同时出现两种格式，中间结构比把领域类型写成“万能解析器”更容易维护。先用字符串接收，再按协议版本或明确规则转换。

package timedecode

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

type eventWire struct {
    Name      string `json:"name"`
    StartedAt string `json:"started_at"`
}

func DecodeLegacyEvent(data []byte) (Event, error) {
    var wire eventWire
    // 中间结构保留外部字符串，转换失败时能带出原始字段上下文。
    if err := json.Unmarshal(data, &wire); err != nil {
        return Event{}, fmt.Errorf("读取外部事件失败: %w", err)
    }
    startedAt, err := time.ParseInLocation("2006-01-02 15:04:05", wire.StartedAt, time.Local)
    if err != nil {
        return Event{}, fmt.Errorf("解析 started_at=%q 失败: %w", wire.StartedAt, err)
    }
    return Event{Name: wire.Name, StartedAt: startedAt}, nil
}

中间结构的价值是把“外部长什么样”和“内部怎么使用”分开。若外部字段可能是 null，可以把接收字段改为 *string 并在转换前判断；若空字符串不代表零时刻，就应该返回可识别错误，而不是默默写入零值。

选择方案时看清空值与兼容边界

还有一个常见误区：把 time.Time 改成 string 后错误消失，并不表示问题解决了。它只是把解析责任推迟到业务代码，之后每个使用点都可能重复写布局、忽略时区或忘记处理空值。

为什么字段是 time.Time 仍然会报错？

因为字段类型只决定目标模型，默认解码仍要求输入是带引号的 RFC3339 字符串。检查 JSON 实际值、分隔符、时区和是否包含引号，再判断要不要适配。

只有日期没有时间怎么办？

如果协议明确是 2026-10-18，应定义日期专用类型并按 2006-01-02 解析；不要把日期强行解释为某个时区的午夜，除非业务契约就是这样定义的。

自定义 UnmarshalJSON 应该放在哪里？

它适合稳定、可复用的外部格式类型。若只有一个接口且迁移规则很特殊，中间结构通常更直观，也更容易在错误中保留字段上下文。

最后可以把判断收口为一句话：外部能遵守 RFC3339，就保留 time.Time；外部格式固定但不同，就给它一个窄的适配类型；外部格式正在迁移，就用中间结构把兼容逻辑关在边界内。