Go encoding/json 的 omitzero 怎么判断空值：IsZero、指针字段与兼容迁移

接口返回里有一个很常见的尴尬：订单没有设置过期时间，JSON 却带着一串 0001-01-01T00:00:00Z；把字段改成 omitempty 后，空切片和零值结构体又出现了与预期不同的行为。Go 1.24 在 encoding/json 中加入 omitzero，它按 Go 类型的零值判断是否省略字段，并优先使用类型提供的 IsZero() bool。

先把 JSON 输出契约定下来

选标签之前，先理清楚调用方期望拿到什么结果：如果字段没有业务含义，能不能直接不返回，还是要求必须返回空数组、零数值或者空字符串？这不是格式偏好问题，而是接口双方要对齐的JSON输出契约。

比如下面的结构体里，就放了三类大家很容易搞混的字段：

type OrderView struct {
    ExpiresAt time.Time `json:"expires_at,omitzero"`
    Labels    []string  `json:"labels,omitzero"`
    Note      string    `json:"note,omitempty"`
}

ExpiresAt 的零时间可以被省略，nil 切片也属于切片类型的零值；但一个已经分配出来、长度为 0 的切片不是零值。Note 则按 omitempty 的 JSON 空值规则处理。把这三个字段混在一个接口里，测试样例必须覆盖每一种状态。

omitzero 和 omitempty 到底差在哪里

可以把它们理解成两套问题：omitzero 先看 Go 值是不是零值，omitempty 看这个值编码后是不是 JSON 意义上的空值。最容易踩坑的就是结构体、时间和非 nil 空切片。

这也是 Go 1.24 发布说明强调 omitzero 的原因：它对有明确零值的类型更直观，尤其是 time.Time。如果两个标签同时出现，字段只要满足其中一套省略条件就不会进入 JSON。

用 IsZero 把业务空值写进类型

有些字段的“空”不是 Go 默认零值。例如一个版本号 0 可能表示“尚未分配”，而负数在业务上也可能代表无效。可以让类型自己实现 IsZero() bool，再使用 omitzero：

type Version int

func (v Version) IsZero() bool {
    return v 

这里的关键不是把判断函数写得更复杂，而是把判断责任放在类型边界内。只要字段类型有这个方法，encoding/json 就会用它判断是否省略；调用方不必在每个组装 DTO 的地方重复写“版本小于等于 0 就不放入响应”。

但要留意方法接收者和零值测试。把 IsZero 只挂在指针接收者上，可能让值字段没有获得你预期的判断；接口层应直接用真实的字段类型写一组 json.Marshal 测试，不要只测业务构造函数。

指针字段要先区分 nil 和指向零值

指针经常用来表达“未设置”和“明确设置为零值”这两种完全不同的状态：

type PatchView struct {
    RetryLimit *int `json:"retry_limit,omitzero"`
}

zero := 0
withZero := PatchView{RetryLimit: &zero}
unset := PatchView{}

unset 会省略 retry_limit，而 withZero 仍会输出 "retry_limit":0。这正是 PATCH 接口常用指针的地方：nil 表示“不改”，指向 0 表示“改成 0”。如果把字段改成普通 int，这个状态就丢了，换标签也救不回来。

迁移时按兼容约束选择标签

已经在线上运行的接口不要全量批量替换标签。可以先挑一个业务影响小的结构体改，跑完对比旧输出和期望的目标输出，再逐个确定每个字段的调整策略：

1. 先梳理所有客户端的字段依赖逻辑：比如移动端是不是把字段缺失当成默认值处理，还是要求服务端哪怕是空数组也要明确返回。
2. 为 time.Time、自定义值类型、指针、slice 和 map 各写一个零值与非零值样例。
3. 只替换语义明确的字段；需要 JSON 空值语义的 slice 继续保留 omitempty。
4. 在 Go 1.24 或更高版本环境跑一遍测试，对比校验JSON内容的时候跳过字段顺序差异，只做结构化内容比对。

项目仍需支持 Go 1.23 时，omitzero 不能直接当作兼容标签使用。升级策略应先调整模块和构建镜像，再把标签变化放进同一个可回滚提交；不要让本地新版本编译通过、线上旧工具链却在发布阶段才失败。

测试别只看字符串，要锁定字段存在性

用完整字符串比较 JSON 容易被字段顺序干扰。更稳妥的方式是先 Marshal，再解码到 map[string]json.RawMessage，专门断言字段是否存在以及存在时的值：

func hasField(t *testing.T, data []byte, name string) bool {
    t.Helper()
    var fields map[string]json.RawMessage
    if err := json.Unmarshal(data, &fields); err != nil {
        t.Fatal(err)
    }
    _, ok := fields[name]
    return ok
}

验收至少包括：零时间是否消失、非零时间是否保留、nil slice 是否消失、空但已分配的 slice 是否保留、指向 0 的指针是否保留，以及自定义 IsZero 的正反两面。只测“正常订单”会把最重要的兼容边界漏掉。

常见问题

omitzero 能不能替代所有 omitempty？

不能。它们的判断基准不同。需要省略空数组、空 map 或空字符串时，omitempty 往往更贴合接口契约；需要识别 Go 零值时，再选择 omitzero。

time.Time 为什么特别适合 omitzero？

因为零时间是一个明确的 Go 零值，而 omitempty 不会把普通结构体按你期望的方式当作空 JSON 值处理。用 omitzero 可以直接表达“未设置时间不出现在响应里”。

自定义 IsZero 会影响 Unmarshal 吗？

不会。omitzero 是 Marshal 时的字段省略选项，反序列化阶段不会用它决定是否接收字段。

为什么 PATCH 响应还要用指针？

指针本身可以保留 nil 和指向零值两种独立状态。只要接口逻辑需要明确区分“用户从未提供该字段”和“用户主动把字段设置为零值”，就不能只靠普通数值字段加 omitzero 标签来替代这个能力。

落地清单

最后可以把迁移检查压缩成四句话：先确认客户端契约，再区分 Go 零值和 JSON 空值；用 IsZero 收拢自定义类型规则；用字段存在性测试验收，最后在目标 Go 工具链上做一次回滚演练。这样改动的重点就从“换一个 tag”回到了“保证接口状态没有被悄悄改写”。