Go encoding/json v2 怎样用 omitzero 区分零值和缺省字段

在 encoding/json/v2 中，想让“没有提供值”的字段不出现在 JSON 里，可以给结构体字段加上 json:",omitzero"。它按 Go 类型系统判断零值：如果类型实现了 IsZero() bool，优先使用这个方法；否则使用该类型的 Go 零值判断。它只影响序列化，不影响反序列化。

官方地址：https://pkg.go.dev/encoding/json/v2

omitzero 适合表达“这个字段没有有效 Go 值时省略”。如果你关心的是 JSON 结果是否为空，则应比较 omitempty；两者都需要时可以同时写。

先用 omitzero 区分零值和缺省字段

下面的结构体把布尔值、数字、时间和指针都交给 Go 零值规则处理。false、0、零时间和 nil 指针会被省略；非零值仍会正常写入 JSON。

package main

import (
    "fmt"
    "time"

    "encoding/json/v2"
)

type UserPatch struct {
    EnabledAt time.Time `json:",omitzero"`
    Retries   int       `json:",omitzero"`
    Enabled   bool      `json:",omitzero"`
    Nickname  *string   `json:",omitzero"`
}

func main() {
    name := "小林"
    patch := UserPatch{Nickname: &name}
    data, err := json.Marshal(patch)
    if err != nil {
        // 序列化失败时直接返回，避免把不完整 JSON 当成成功结果。
        panic(err)
    }
    fmt.Println(string(data))
}

这里的 Nickname 是非 nil 指针，因此会保留；其余字段处于零值状态，会从输出对象中消失。字段缺省并不等于写入 JSON 的 null，这正是补丁请求、可选配置和部分更新对象常用的表达方式。

omitzero 与 omitempty 的差异在容器上最明显

两者都能省略一些看起来“没有内容”的字段，但判断依据不同。omitzero 看 Go 零值；omitempty 看字段编码后是否是 JSON null、空字符串、空对象或空数组。

type Payload struct {
    NilItems   []string          `json:"nil_items,omitzero"`
    EmptyItems []string          `json:"empty_items,omitzero"`
    NilTags    map[string]string `json:"nil_tags,omitempty"`
    EmptyTags  map[string]string `json:"empty_tags,omitempty"`
}

// nil 切片和 nil map 是 Go 零值；make 出来的空容器不是零值。
payload := Payload{
    EmptyItems: make([]string, 0),
    EmptyTags:  make(map[string]string),
}

对这个例子，NilItems 会因零值被省略，但非 nil 的 EmptyItems 不会；omitempty 则会把空数组和空对象也视为空。选择时先问一句：接口要表达“未提供”，还是要表达“明确提供了一个空集合”？

用 IsZero 定义业务上的“没有值”

有些类型的零值不是简单的空字符串或数字。例如，一个带单位的金额、坐标或业务状态，可能需要把“未设置”的几种内部形态都当成零值。这时在类型上提供 IsZero，字段标签不需要写复杂逻辑。

type Money struct {
    Cents    int64
    Currency string
}

func (m Money) IsZero() bool {
    // 金额和币种都未设置时，才把它视为可省略的业务零值。
    return m.Cents == 0 && m.Currency == ""
}

type Invoice struct {
    Total Money `json:",omitzero"`
}

实现 IsZero 时要保持判断稳定、无副作用，并让团队知道它服务于序列化语义。若 Currency 已经有值，即使金额为 0，也可能不应被当成“未提供”，因此不要只凭字段数量机械判断。

字段很多时可以使用统一选项

除了逐字段添加标签，encoding/json/v2 还提供 OmitZeroStructFields。它相当于对结构体字段统一启用零值省略，仍然遵守 IsZero 和 Go 零值规则。

type Response struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Detail  string `json:"detail"`
}

// 统一省略零值字段，适合由同一层协议集中控制输出形状。
data, err := json.Marshal(Response{Code: 200}, json.OmitZeroStructFields(true))
if err != nil {
    // 发布接口响应前先保留原始错误，便于定位编码失败原因。
    panic(err)
}
_ = data

统一选项适合协议边界清晰、字段约定一致的响应对象。若某些字段必须始终出现，就不要只依赖全局选项，应给它保留显式字段策略或在接口契约中明确“必填且允许零值”。

最后检查序列化和反序列化的边界

omitzero 的职责是决定 marshaling 时哪些字段不写入。它不会因为字段缺少就替你改变 unmarshaling 的业务判断，也不会把“缺少字段”和“显式传入零值”自动变成同一种业务事件。

如果接口需要区分“客户端没有提交字段”和“客户端提交了 0/false/空集合”，仅靠一个普通值字段不够，通常还要使用指针、可选包装类型或额外的存在性标记。omitzero 负责输出形状，是否允许更新、是否清空数据仍由业务层决定。

常见问题

omitzero 会影响 JSON 反序列化吗？

不会。官方文档将它定义为 marshaling 选项；读取 JSON 时仍需由结构体字段类型和业务逻辑决定缺省值如何处理。

空切片为什么没有被 omitzero 省略？

非 nil 的空切片不是 Go 零值。若目标是把空数组也省略，应考虑 omitempty，或在业务层把空集合规范化为 nil。

omitzero 和 omitempty 能同时写吗？

可以。两者同时指定时，只要满足任一省略条件就不会输出；但应先明确接口契约，避免把“未提供”和“明确为空”混为一谈。

什么时候应该实现 IsZero？

当类型的业务零值不等于语言默认零值时实现，例如必须同时检查金额和币种的值。判断方法应简单、稳定，并与序列化契约保持一致。