Go JSON 时间字段为什么解析失败

Go JSON 时间字段解析失败，常见原因是输入并不是 time.Time 默认接受的带时区 RFC3339 字符串：日期与时间之间用了空格、没有时区、传了数字时间戳，或者传入了空字符串。先确认 JSON 值的类型，再核对时间格式；修改 json 标签名称不会改变时间解析规则。

官方文档入口：https://pkg.go.dev/time；JSON 接口文档：https://pkg.go.dev/encoding/json。本文围绕标准库 encoding/json 的普通字段解码，不展开其他序列化库或自定义框架行为。

1. 把字段契约写成可以判断的条件

先确定 at 表示一个明确的时刻，还是某个地区的墙上时间。对于跨系统事件，优先让发送方提供类似 2026-10-22T09:20:30+08:00 的字符串，日期与时间之间有大写 T，末尾有偏移量；UTC 也可用 Z。默认 time.Time 解码不是“自动猜日期”的功能。

如果输入只有 2026-10-22，它更像日历日期；如果输入是 2026-10-22 09:20:30，它没有说明属于哪个地区。这两种数据都不应偷偷补成服务器本地时区。数字时间戳则应单独约定单位，不能认为 JSON 数字会自动转换成 time.Time。

2. 将标准输入和旧协议分开处理

排障可以拆成三个独立问题：外层 JSON 是否有效、at 的 JSON 类型是否符合合同、日期与时区是否可以解释。只有第一项成功不代表时间合法。反过来，格式错误也不一定是 JSON 语法错误，底层时间解析器可能已经收到字符串并拒绝了它。

推荐保留两个明确入口：新接口使用标准 Event，固定旧来源使用独立输入对象。不要给全项目的 time.Time 添加隐式多格式猜测，更不要在失败时直接返回当前时间或零时间。格式不一致应在接口边界被发现，而不是进入数据库后再猜原因。

3. 标准字段保留 time.Time，旧字段显式解析

下面是一个可保存为 main.go 的完整教学程序。decodeStandard 接受 RFC3339 字符串；decodeLegacy 只为已约定的无时区旧格式服务。代码没有在本文环境执行，后文输出均为依据输入推导的预期行为。

package main

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

type Event struct {
    At *time.Time `json:"at"` // 指针允许识别本次新对象中的空值
}

func decodeStandard(data []byte) (time.Time, error) {
    var event Event // 每次解码使用新对象，避免沿用旧字段
    if err := json.Unmarshal(data, &event); err != nil {
        return time.Time{}, fmt.Errorf("decode event: %w", err)
    }
    if event.At == nil { // 本接口把缺失和 null 都视为必填错误
        return time.Time{}, fmt.Errorf("at is required")
    }
    return event.At.UTC(), nil // 改变显示时区，不改变代表的时刻
}

func decodeLegacy(data []byte, loc *time.Location) (time.Time, error) {
    var input struct {
        At *string `json:"at"` // 旧协议先按字符串读取，再解释日期
    }
    if loc == nil {
        return time.Time{}, fmt.Errorf("location is required")
    }
    if err := json.Unmarshal(data, &input); err != nil {
        return time.Time{}, fmt.Errorf("decode legacy event: %w", err)
    }
    if input.At == nil || *input.At == "" {
        return time.Time{}, fmt.Errorf("at is required")
    }
    const layout = "2006-01-02 15:04:05" // 使用 Go 的参考时间，而非 YYYY-MM-DD
    parsed, err := time.ParseInLocation(layout, *input.At, loc)
    if err != nil { // 日期不成立或格式不匹配时不接收零值
        return time.Time{}, fmt.Errorf("parse legacy at: %w", err)
    }
    return parsed.UTC(), nil
}

func main() {
    t, err := decodeStandard([]byte(`{"at":"2026-10-22T09:20:30+08:00"}`))
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(t.Format(time.RFC3339)) // 预期为同一时刻的 UTC 表达

    loc, err := time.LoadLocation("Asia/Shanghai") // 来源合同约定的地区，不使用机器默认值
    if err != nil {
        fmt.Println(err) // 部署环境缺少时区数据时明确失败
        return
    }
    old, err := decodeLegacy([]byte(`{"at":"2026-10-22 09:20:30"}`), loc)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(old.Format(time.RFC3339)) // 只为明确约定的旧协议提供兼容
}

decodeStandard 使用 *time.Time，是为了在新对象里把缺失和 null 合并判为必填错误。使用普通 time.Time 也可以解码合法字符串，但“解析没有报错”并不等于业务必填条件已经满足。每次建立新对象还能避免遗漏字段时沿用上一次的数据。

旧协议用 *string 保存输入，再调用 ParseInLocation。layout 必须使用 Go 参考时间的对应数字：2006 表示年，01 表示月，02 表示日，15 表示二十四小时，04 和 05 表示分秒。它不是 Java 或其他语言中常见的 YYYY-MM-DD 模板。

4. 时区必须来自数据合同，而不是部署机器

同一个 09:20:30，放在不同地区可能代表不同的时刻。Parse 在输入没有时区信息时按 UTC 解释；ParseInLocation 可以明确指定地区。示例选择 Asia/Shanghai，只因为假设旧来源合同明确约定这个地区，不是建议所有系统都统一这样解释。

time.LoadLocation 的错误必须处理，容器中可能缺少所需时区数据。固定偏移量只描述偏移，不等于包含地区历史及夏令时规则的时区；涉及其他地区、历史日期或夏令时重复/跳过的本地时间，还需要业务层制定歧义处理规则，不能只靠宽松解析猜一个结果。

本例的两个输入在该约定下都应格式化为 2026-10-22T01:20:30Z。读者可自行运行 go run main.go 核对。若标准分支改为无时区字符串，应得到错误；若旧分支输入不成立的日期，也应被拒绝，而不是拿返回的零值继续处理。

5. 用速查表缩小问题范围

返回错误后应丢弃本次解码对象，不把可能部分更新的字段用于写库。内部诊断可以用 %w 保留错误原因，但对外响应不应直接暴露完整原始请求；记录字段名、来源和预期格式通常比记录整份敏感正文更合适。

6. 小数秒、空值和格式标签还容易混淆什么

有毫秒就一定解析失败吗？不是。RFC3339 时间可以包含小数秒，不能看到小数点就先截断它。先检查缺失时区、空格分隔和输入类型；如果业务只允许固定精度，还需另行明确限制。

omitempty 会让输入空字符串自动跳过吗？不会。它控制序列化时的省略，不是接收端的格式转换器，也不能代替必填检查。

指针能区分缺失和 null 吗？在本例每次新建对象的方式下，两者都会表现为 nil，因此不能区分。如果补丁接口需要三态语义，应额外保存字段存在标志或用 RawMessage 判断键是否存在，而不是把这份简单必填示例直接当成更新协议。

处理路线应保持稳定：新接口约定带时区的标准字符串；旧接口以独立输入类型承担兼容；解析成功后再检查业务约束并按需要统一展示时区。不要把解析失败“修复”为一个看似正常却含义错误的日期。

参考：time.Time.UnmarshalJSON、time.ParseInLocation、encoding/json.Unmarshal。