Go JSON 时间字段如何兼容多格式

Go JSON 时间字段兼容多格式，可以为字段定义自己的 UnmarshalJSON：先解出字符串，再按有限的格式白名单尝试，成功后统一保存和输出。无时区格式必须约定业务时区；字段缺失、null 与错误输入也要分别处理。只修改 json 标签不会让 time.Time 自动认识任意日期格式。

官方文档地址：https://pkg.go.dev/encoding/json；时间解析文档：https://pkg.go.dev/time。

用户任务：让旧输入可用且输出统一

设计预约表单接口时，我会先让用户知道输入代表哪个时刻，再考虑服务端多接受几种写法。比如“2026-10-31 09:15:00”只有钟面信息，“2026-10-31T09:15:00+08:00”还带偏移；如果悄悄把两者当成同一时刻，兼容层就改变了业务含义。

这里限定一个小组件：新客户端提交带偏移的标准时间，旧客户端允许横线或斜线日期加空格时间；旧格式统一按 UTC 解释，返回值也统一为 UTC 标准时间字符串。这是本文示例的契约，不表示所有业务都该采用 UTC 解释旧输入。

交互拆解：先写清字段状态契约

前端本地日期时间控件经常不携带偏移，不能把它的文本直接冒充 UTC。若页面代表用户所在地的预约，应该明确传递偏移或时区标识，或由接口固定一个已说明的业务时区。日期型字段只表示某一天时，更适合单独的日期类型，不应为方便解析而擅自补成午夜时刻。

组件实现：封装 JSON 时间适配器

package main

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

// 时间值采用命名字段，避免匿名嵌入意外提升 time.Time 的方法。
type InputTime struct {
    Value   time.Time
    Present bool
    Valid   bool
}

func (dst *InputTime) UnmarshalJSON(data []byte) error {
    // 先用临时值解析，错误时不覆盖原对象。
    next := InputTime{Present: true}
    if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
        *dst = next
        return nil
    }
    var text string
    if err := json.Unmarshal(data, &text); err != nil {
        return errors.New("时间必须是字符串或 null")
    }
    if text == "" || len(text) > 64 {
        return errors.New("时间字符串不能为空且不能超过64字节")
    }

    parsed, err := time.Parse(time.RFC3339Nano, text)
    if err != nil {
        // 业务约定：这两种无时区旧格式均按 UTC 解释。
        for _, layout := range []string{
            "2006-01-02 15:04:05",
            "2006/01/02 15:04:05",
        } {
            candidate, parseErr := time.ParseInLocation(layout, text, time.UTC)
            // 回写比对收紧旧格式，拒绝额外的小数秒或不同宽度。
            if parseErr == nil && candidate.Format(layout) == text {
                parsed, err = candidate, nil
                break
            }
        }
    }
    if err != nil {
        return errors.New("请使用带时区的标准时间或指定的旧日期时间格式")
    }
    next.Value, next.Valid = parsed.UTC(), true
    *dst = next
    return nil
}

func (v InputTime) MarshalJSON() ([]byte, error) {
    // 输入存在性用于业务判断，输出空值统一使用 null。
    if !v.Valid {
        return []byte("null"), nil
    }
    return v.Value.UTC().MarshalJSON()
}

type Appointment struct {
    StartsAt InputTime `json:"starts_at"`
}

func main() {
    samples := []string{
        `{"starts_at":"2026-10-31T09:15:00+08:00"}`,
        `{"starts_at":"2026-10-31 09:15:00"}`,
        `{"starts_at":"2026/10/31 09:15:00"}`,
        `{"starts_at":null}`,
        `{}`,
        `{"starts_at":""}`,
    }
    for _, input := range samples {
        // 每份请求使用新对象，避免缺失字段保留上份请求的值。
        var item Appointment
        if err := json.Unmarshal([]byte(input), &item); err != nil {
            fmt.Println("starts_at 格式错误:", err)
            continue
        }
        encoded, err := json.Marshal(item)
        if err != nil {
            fmt.Println("编码失败:", err)
            continue
        }
        fmt.Printf("present=%t valid=%t json=%s\n",
            item.StartsAt.Present, item.StartsAt.Valid, encoded)
    }
}

InputTime 是值字段，它的 UnmarshalJSON 能处理显式 null，并记录 Present；对象中没有这个字段时，方法不会被调用。Valid 描述是否有有效时间，不依赖 Value.IsZero()，因此合法的零值时刻不会因为长得像默认值就被当作缺失。

标准分支使用 Go 的 RFC3339Nano 解析器，接受其支持的小数秒和数值偏移。这里并未另写逐字节的 RFC 语法检查器，不能把组件宣传为严格格式认证器。两个旧布局则通过解析后再格式化比对收紧，避免 time.Parse 对小数秒等兼容行为扩大旧接口承诺。

示例没有调用 TrimSpace 去修改已经解码出来的字符串，所以时间文本首尾有空格会失败；JSON 字符串外的空白由 JSON 解码处理。字符串先经 json.Unmarshal 解码，转义字符能按 JSON 规则解释，不需要手工去掉引号。

实现先解析临时变量，整个字段成功后才赋值。外层 JSON 如果出现任何错误，调用方仍应丢弃这份请求对象，因为其他字段可能已被更新。不能因为单个字段有临时值，就声称整份 JSON 更新具有事务性。

可访问性：让格式错误能够被修正

用户可修正的错误应该显示在预约时间输入旁，例如“请输入含时区时间，或使用 YYYY-MM-DD HH:mm:ss；旧格式按 UTC”。我更倾向于显示认可的格式与时区，而不是把服务端 ParseError、内部结构名和整段原始请求回显给用户。

如果页面做成可交互表单，应让说明文本与输入关联，错误提示能被辅助技术读取，提交失败后保留用户原文本并把焦点引向需要修正的字段。颜色可以辅助提示，但还要有文字说明。本文配图只解释数据结构，不冒充已经实现的表单界面。

接口层可将该字段错误映射为 starts_at 的结构化错误码，再由前端给出本地化提示。不要解析错误字符串来推断字段名；有多个自定义时间字段时，应在父对象解码层显式包装字段信息。示例的 main 只处理一个字段，因此展示时直接标记 starts_at。

性能检查：控制尝试范围与输入大小

这个组件最多尝试一个标准布局和两个旧布局。选择有限白名单，是为了让接口承诺可维护，而不是宣称它比其他解析器更快。只有新增了真实输入来源，才应加入新格式，并说明是否存在日月顺序歧义。

字符串的 64 字节上限只约束已解码的时间文本，不能代替 HTTP 请求体大小限制。服务端应在读取 JSON 前限定请求体，在组件外管理输入总量。大量请求需要性能结论时，应以自己的负载另行测量；本文未执行代码，也没有性能测试数据。

将代码保存为 main.go 后，读者可执行下面的命令，观察各样本的 Present、Valid 与编码结果。不要比较不同格式的原始字符串来判断同一时刻；应在成功解析后比较时间值。

# 在保存 main.go 的目录中运行样本，观察字段状态与规范输出
go run main.go

边界状态：缺失、时区与回写

输入带 +08:00 的 09:15 与旧格式按 UTC 解释的 09:15，相差八小时。这不是格式化造成的丢失，而是两个输入表达的时区契约不同。若业务的旧数据实际属于 Asia/Shanghai，必须在适配层采用该业务 Location，不能把 UTC 解析后的值再换个显示时区当作修复。

需要历史时区和夏令时规则时，应加载明确的 IANA 时区并处理加载错误。夏令时切换处可能出现不存在或重复的本地钟面时间，单靠无偏移字符串未必能唯一定位时刻。这类预约最好要求调用者补充足以消歧的信息。

PATCH 接口可把 Present=false 解释为不修改，把 Present=true 且 Valid=false 解释为清空，Valid=true 解释为设置时间。该决策应由业务层执行。对普通创建接口，若预约时间必填，还需在解析成功后拒绝缺失或 null，不能把“合法 JSON”视作“满足预约规则”。

为什么缺失字段回写后变成 null？

本例的 MarshalJSON 只统一值，不保留输入对象的字段集合；缺失与 null 都输出 null。若输出必须省略未出现字段，应另建响应 DTO 或由父对象根据 Present 组装，不能期待这个值字段自动完成。

把字段换成 *InputTime 更简单吗？

指针适合只关心有值或无值的场景，但对新对象而言，缺失与显式 null 通常都会成为 nil，不利于区分 PATCH 的“不改”和“清空”。本文采用值字段正是为了显式保留存在性。

能自动识别秒级与毫秒级时间戳吗？

本例明确拒绝数字。确需兼容时，应使用独立字段或显式单位契约，不按位数猜测，也不要先转 float64 再推断精度。多格式兼容应有边界，不能变成任意值都能被解释的黑箱。

技术依据：encoding/json 官方解码说明、time 官方解析与时区说明。本文代码与状态契约为独立设计。