登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go问答

Go time.Time.UnmarshalJSON 遇到 null 时怎么判断是否为零值

来源:17golang原创

时间:2026-11-17 11:33:46 254浏览 收藏

在 Go 中,JSON 的 null 不等于“把 time.Time 设置成零值”。对值类型字段来说,time.Time.UnmarshalJSON 收到 null 时会保留字段原来的状态;如果字段原本就是零值,看起来才会像是“解析后变成零值”。

因此,判断结果要先问清楚:字段是 time.Time 还是 *time.Time,解析前有没有旧值,以及业务是否需要区分“未提供”“明确为 null”和“有具体时间”。下面按这三个判断展开。

先看 null 到底改变了什么

官方 time.Time.UnmarshalJSON 接受 RFC3339 时间字符串。输入是 JSON null 时,它返回空错误,但不会覆盖接收者已有的时间值。这是一个“保持原状态”的语义,不是“写入零值”。

JSON null和RFC3339字符串进入encoding/json与time.Time.UnmarshalJSON后连接到时间字段和错误边界的静态结构图
图1:输入形态、解码入口与 time.Time.UnmarshalJSON 的静态关系说明图,不是运行截图或执行证据。

可以把值字段的判断压缩成两种情况:

  • 字段原来是零值,收到 null 后仍是零值;
  • 字段原来已有时间,收到 null 后仍保留这段时间。

用 IsZero 时不要把原因归给 null

IsZero 只回答当前 time.Time 是否为零值,它不能告诉你这个状态是初始化得到的、JSON 没有覆盖,还是业务代码主动写入的。下面的两个例子故意只改变解析前的状态。

package main

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

type Payload struct {
    PublishedAt time.Time `json:"published_at"`
}

func main() {
    // 零值字段遇到 null 后仍是零值;不是 null 主动创建了零值。
    var empty Payload
    if err := json.Unmarshal([]byte(`{"published_at":null}`), &empty); err != nil {
        panic(err)
    }
    fmt.Println(empty.PublishedAt.IsZero()) // true

    // 先放入旧时间,再解码 null;值字段会保留原来的时间。
    existing := Payload{PublishedAt: time.Date(2026, 11, 17, 9, 0, 0, 0, time.UTC)}
    if err := json.Unmarshal([]byte(`{"published_at":null}`), &existing); err != nil {
        panic(err)
    }
    fmt.Println(existing.PublishedAt.IsZero()) // false
}

这段代码的关键不是 IsZero,而是解析前的字段状态。做 PATCH、配置合并或默认值覆盖时,如果把已有对象直接拿来反序列化,null 可能被误读成“清空请求”。

时间字符串和 null 的错误边界不同

对于合法的 RFC3339 字符串,time.Time.UnmarshalJSON 会解析出时间;对于 null,它不报错并保留原值;对于带引号但格式不合法的字符串,则会返回解析错误。调用方要把“空值语义”和“格式错误”分开处理。

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

func decodeEvent(data []byte) (Event, error) {
    var event Event

    // 让 encoding/json 负责调用 time.Time.UnmarshalJSON,并保留原始错误。
    if err := json.Unmarshal(data, &event); err != nil {
        // 非法 RFC3339 字符串要返回错误,不能当成 null 忽略。
        return Event{}, fmt.Errorf("解析 started_at 失败: %w", err)
    }
    return event, nil
}

// 合法字符串、null 和非法字符串的处理结果不同:
// {"started_at":"2026-11-17T09:00:00Z"} -> 写入时间
// {"started_at":null}                     -> 保留当前值
// {"started_at":"not-a-time"}           -> 返回解析错误

这里的输出注释是语义对照,不是某次本地运行日志。真正接入业务时,建议把上层错误包装成包含字段名的错误,让接口层能够区分 400 参数错误和默认值处理。

需要表达可空时间时使用 *time.Time

如果业务定义是“有时间”或“没有时间”,指针字段通常比值字段更直观。对 *time.Time 字段,JSON null 可以映射为 nil;具体时间则得到一个非 nil 指针。

Order结构中的time.Time值字段和指针字段对比JSON null、零值、已有时间与nil的静态数据关系图
图2:值字段与指针字段表达可空时间的静态数据关系说明图,不是运行截图或执行证据。
type UpdateOrder struct {
    // 值字段无法单独表达 null 与未覆盖的差异。
    ReviewedAt time.Time `json:"reviewed_at"`
    // 指针字段用 nil 表达没有时间,用非 nil 表达具体时间。
    DeliveredAt *time.Time `json:"delivered_at"`
}

func readUpdate(data []byte) (UpdateOrder, error) {
    var update UpdateOrder
    if err := json.Unmarshal(data, &update); err != nil {
        // 非法时间格式仍然是输入错误,不能把指针置 nil 后吞掉。
        return UpdateOrder{}, fmt.Errorf("解析订单时间失败: %w", err)
    }
    return update, nil
}

// {"delivered_at":null} 的结果是 DeliveredAt == nil。
// {"delivered_at":"2026-11-17T09:00:00Z"} 的结果是 DeliveredAt != nil。
// ReviewedAt 仍然是值字段,不能据此区分 null 与缺失。

注意,指针只解决“有没有一个时间值”的建模问题。如果接口还要区分字段缺失和明确传入 null,单独的 *time.Time 仍不够:两者都可能落到 nil,需要额外的存在标记。

三态输入要用带状态的包装类型

PATCH 请求常见三态:字段没出现表示“不修改”,字段为 null 表示“清空”,字段为时间表示“设置”。可以给时间值增加 Set 和 Valid 两个状态位,把这三种情况从普通 time.Time 里分离出来。

type OptionalTime struct {
    Time  time.Time
    Set   bool // 字段是否在 JSON 中出现
    Valid bool // 出现后是否不是 null
}

func (o *OptionalTime) UnmarshalJSON(data []byte) error {
    // 进入该方法本身就说明字段已经出现。
    o.Set = true
    if string(data) == "null" {
        // null 表示清空,不把旧时间误认为新值。
        o.Time = time.Time{}
        o.Valid = false
        return nil
    }

    var value time.Time
    if err := json.Unmarshal(data, &value); err != nil {
        // 保留 RFC3339 的格式错误,交给调用方返回参数错误。
        return err
    }
    o.Time = value
    o.Valid = true
    return nil
}

// Set=false:字段缺失,业务通常保持原值。
// Set=true、Valid=false:明确传入 null,业务可以清空。
// Set=true、Valid=true:传入具体时间,业务可以更新。

这个包装类型的重点是“出现过”与“有值”分开记录。若接口不需要三态,优先使用简单的 *time.Time;若是普通响应模型且零值已经有明确业务含义,使用 time.Time 更省心。

最后用一张表做选择

业务含义建议字段null 的结果判断方式
始终需要一个时间,零值可接受time.Time保留原值IsZero() 只能判断当前状态
只区分有时间和无时间*time.Timenil比较指针是否为 nil
区分缺失、null、具体时间状态包装类型由 Set/Valid 表达先看 Set,再看 Valid

常见追问

time.Time.IsZero() 能判断 JSON 是否传了 null 吗?

不能。它只判断当前时间是否是零值,不记录 JSON 输入来源。

为什么给 time.Time 字段传 null 后旧时间还在?

因为 time.Time.UnmarshalJSON 对 null 保持接收者原状态;这不是清空操作。

字段缺失和 null 都要清空时怎么办?

先确定接口契约。如果缺失和 null 都代表清空,可以在请求层统一归一化;如果三态都重要,就使用带 Set、Valid 的包装类型。

记住一句话:值字段的 null 是“保留原状态”,指针字段的 null 是“得到 nil”,而三态 PATCH 需要自己记录字段是否出现。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>