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 时,它返回空错误,但不会覆盖接收者已有的时间值。这是一个“保持原状态”的语义,不是“写入零值”。

可以把值字段的判断压缩成两种情况:
- 字段原来是零值,收到
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 指针。

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.Time | nil | 比较指针是否为 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 需要自己记录字段是否出现。
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习