Go encoding/json 时间字段为什么不能直接解析怎样构造最小复现

Go 的 encoding/json 可以直接解码 time.Time 字段，但输入必须符合该类型的 JSON 约定：通常是带引号的 RFC3339 时间字符串。常见的空格分隔日期、纯日期或数字时间戳不会自动按业务含义转换。构造最小复现时，保留一个 time.Time 字段和一条原始 JSON，先区分 JSON 语法错误、字段类型不匹配与时间格式错误。

官方地址：https://pkg.go.dev/encoding/json

时间类型文档：https://pkg.go.dev/time#Time.UnmarshalJSON

把请求缩减成一个时间字段

面对“数据库里看起来正常，接口却失败”的场景，我会先把数据库、路由、绑定框架和业务处理拿掉，只留下标准库与原始输入。下面程序提供三个对照输入：无时区旧格式、带偏移的 RFC3339 字符串和 JSON 数字。它是可自行运行的复现程序，本文不把示例描述成已执行的结果。

package main

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

func main() {
    type Event struct { At time.Time `json:"at"` }
    samples := []string{
        `{"at":"2026-11-07 09:30:00"}`,
        `{"at":"2026-11-07T09:30:00+08:00"}`,
        `{"at":1794015000}`,
    }
    for _, raw := range samples {
        // 每次使用新对象，避免上一条输入留下字段值。
        var e Event
        err := json.Unmarshal([]byte(raw), &e)
        if err != nil {
            fmt.Printf("失败：%T：%v\n", err, err)
            continue // 失败对象不进入业务处理。
        }
        fmt.Println("成功：", e.At.Format(time.RFC3339))
    }
}

按 time.Time 的解码约定，第一个字符串格式不符合要求；第二个字符串属于接受的形式；第三个输入不是带引号的时间字符串。示例中的整数只是为了说明 JSON 类型差异，不能通过数值外观判断它应按秒、毫秒还是其他单位解释。

确认失败发生在时间格式层

JSON 本身没有专用的日期类型。解码器看到目标字段实现了 UnmarshalJSON，就把对应 JSON 值交给该方法处理，而不是替你猜日期格式。字段上的 json 标签只指定字段名等 JSON 映射规则，不会设置 time.Parse 使用的布局；给其他框架使用的时间格式标签，也不会自动改变直接调用 json.Unmarshal 的行为。

排查时应检查真实请求中的引号、分隔符和时区偏移，并保留错误类型与错误链。不要只截取页面上格式化后的时间文本，它可能与实际传输值不同。json.Valid 即使返回 true，也只能说明 JSON 语法成立，不能证明某个字段能转换为 time.Time。

保留旧格式时显式转换

若上游短期内只能发送 2026-11-07 09:30:00，先用接收结构保存字符串，再进行显式转换，通常更容易解释失败原因。以下辅助函数选择严格的旧格式和调用方提供的业务时区；不要默默依赖部署机器的本地时区。

package eventinput

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

// ParseLegacy 仅接受约定的无时区旧格式；时区由调用方显式提供。
func ParseLegacy(data []byte, loc *time.Location) (time.Time, error) {
    if loc == nil { return time.Time{}, fmt.Errorf("缺少业务时区") }
    var wire struct { At *string `json:"at"` }
    if err := json.Unmarshal(data, &wire); err != nil {
        return time.Time{}, fmt.Errorf("解析请求: %w", err)
    }
    // 本接口把缺失、null 和空字符串都视作必填项错误。
    if wire.At == nil || *wire.At == "" {
        return time.Time{}, fmt.Errorf("at 必须为非空时间字符串")
    }
    parsed, err := time.ParseInLocation("2006-01-02 15:04:05", *wire.At, loc)
    if err != nil { return time.Time{}, fmt.Errorf("解析 at 旧格式: %w", err) }
    return parsed, nil
}

这里的布局 2006-01-02 15:04:05 使用 Go 的参考时间写法。若输入已包含时区偏移，应使用相符的布局，不要先删掉偏移再解析。对于夏令时切换产生的歧义本地时间，应另行制定接口规则，不能把“不报错”当作业务时间一定唯一。

选择迁移方式与观察指标

如果协议明确使用秒时间戳，可在接收 int64 后调用 time.Unix；毫秒协议则使用 time.UnixMilli。不要为了“兼容所有格式”按位数猜单位或依次尝试大量布局，这会让错误数据被另一种规则意外接受。迁移阶段可以观察各格式的请求数量、转换失败类别和仍使用旧格式的调用方，不必凭空宣称某种行业趋势或性能收益。

自定义 UnmarshalJSON 适合确实重复使用的协议类型，但新增类型后还要考虑 MarshalJSON 的输出形式，避免输入接受旧格式、输出却悄悄改成另一种表示。只有一个入口需要适配时，显式接收结构往往更容易维护。

空值和缺失字段如何处理

null 能表示必填时间吗？业务必须自行决定。time.Time 对 JSON null 的处理不能代替必填校验；缺失字段也不会自动产生错误。若重复复用接收对象，旧值还可能掩盖缺失输入，示例因此每次都新建对象。

使用 *time.Time 能区分 null 与缺失吗？新对象中两者通常都表现为 nil。若必须区分“未提供”和“显式清空”，应使用 RawMessage 或带存在标记的自定义接收类型。第二段代码明确把两者统一拒绝。

为什么有些框架同样输入却能解析？先确认框架是否调用了自己的绑定器、自定义类型或字符串适配逻辑。不要把框架层行为推广为标准库的默认行为。

最小复现应固定原始输入、目标类型和解析入口。先让错误稳定落到一个字段，再选择调整上游协议或在接收边界明确转换，避免把格式不一致隐藏成零值时间。