json/v2 的 omitzero 与 omitempty 选择依据

在 json/v2 里，选择这两个标签的关键不是记住名称，而是先问一句：你要按 Go 值本身判断，还是按它编码后的 JSON 形态判断？omitzero 看 Go 零值，类型实现了 IsZero() bool 时优先使用这个方法；omitempty 看 JSON 的 null、空字符串、空对象或空数组。布尔值和数字通常优先用 omitzero，集合字段通常用 omitempty，两种条件都满足才省略时再组合使用。

官方资料：https://go.dev/src/encoding/json/v2/doc.go

先分清 Go 零值和 JSON 空值

这是一次“判断层级”的选择。对 int 来说，0 是 Go 零值；对 string 来说，空字符串既是 Go 的零值，也会编码成 JSON 空字符串，所以很多场景下两者效果相同。但 nil 切片和空切片不能混为一谈：omitzero 关注是否为 nil，omitempty 关注编码结果是否为空数组。

还要注意边界：两个标签都只在编码结构体时生效。它们不会让解码输入自动补值，也不会改变字段在 Go 内存中的零值。

按字段类型选择标签

可以先用下面这张速查表确定第一版，再结合接口契约修正：

例如接口中要区分“数量明确为 0”和“数量没有提供”，就不要把 0 交给只按空值筛选的写法；如果要表达“空列表与未传列表都不输出”，omitempty 更贴近接口语义。下面的代码只展示标签关系，注释解释了每个字段的意图：

type Payload struct {
	// Count 的 0 表示未设置，按 Go 零值省略。
	Count int `json:"count,omitzero"`
	// Enabled 的 false 表示默认关闭，按 Go 零值省略。
	Enabled bool `json:"enabled,omitzero"`
	// Labels 为空数组时没有接口信息，按 JSON 空值省略。
	Labels []string `json:"labels,omitempty"`
	// Name 为空字符串时不返回可读名称。
	Name string `json:"name,omitempty"`
}

处理 IsZero 与组合标签

当类型有业务化的零值定义时，omitzero 的表达力更强。官方文档以 time.Time.IsZero 为例：时间字段是否省略不应靠字符串格式猜测，而应由类型自己的零值规则决定。

如果字段同时写成 json:",omitzero,omitempty"，只要满足“是 Go 零值”或“会编码为空 JSON 值”其中一个条件，就会被省略。这个组合适合你既想隐藏 nil 指针、0、false，又想隐藏空集合的场景；但它也会让接口无法区分“客户端明确传空”和“客户端没有传”，要先确认协议是否允许丢失这个区别。

迁移旧代码并做边界检查

从旧版 encoding/json 迁移到 json/v2 时，优先搜索 omitempty 出现在 bool、数字、指针、接口上的字段。v2 的 omitempty 以 JSON 空值为准，这些字段通常应改成 omitzero，或在确有必要时使用 OmitEmptyWithLegacySemantics 保留旧语义。

1. 列出每个字段的三种状态：未设置、显式零值、非零值。
2. 分别确认空切片、nil 切片、空 map 和 nil map 的接口结果。
3. 检查自定义 IsZero 是否与业务中的“未提供”一致。
4. 为编码结果写表格驱动测试；解码测试单独验证，因为这两个标签对解码无效。

相关问题

omitzero 和 omitempty 能一起写吗？

可以。组合后满足零值或 JSON 空值任一条件就省略，但会减少接口区分状态的能力。

空切片应该选哪个？

若空切片编码为空数组时就不需要字段，选 omitempty；若只想隐藏 nil，使用 omitzero。

这两个标签会影响 JSON 解码吗？

不会。它们是编码时的字段省略规则，解码仍需单独设计缺失字段和显式零值的处理。