Go API 的空值契约怎么保留：按场景选择 omitempty、omitzero 与指针字段

Go API 里最容易被忽略的兼容问题，不是字段名，而是“这个字段没有值”到底代表什么。客户端可能需要区分未提交、显式清空、零值和真正的业务值。实用的判断规则是：按 Go 零值省略就用 omitzero，按 JSON 的 null、空字符串、空数组或空对象省略才用 omitempty；如果必须保留“有没有传过”这一层信息，就使用指针字段。encoding/json/v2 还改变了 omitempty 对布尔值和数字的直觉语义，迁移前要先固定契约。

先决定 API 要表达几种状态，再决定 struct tag；标签只能控制 marshaling，不能替你补回一次已经丢失的“是否提交”信息。

先把三种状态拆开：缺失、null 和具体值

以部分更新用户资料为例，Age int 无法区分请求里没有 age，还是客户端明确传了 0。改成 *int 后，nil 可以表示“没有提交”，非 nil 且指向 0 才表示“明确改成 0”。但指针为 nil 在输出 JSON 时通常会编码成 null，是否要让字段消失，还要由 omitzero 或 omitempty 决定。

omitzero 和 omitempty 不是同义词

官方文档把两者分成两套判断：omitzero先看类型有没有 IsZero() bool，否则判断 Go 零值；omitempty则看该字段编码后是不是 JSON null、空字符串、空对象或空数组。对 slice 和 map 来说，nil 与空容器就可能产生不同结果：omitzero只会省略 nil，omitempty会把两者都视为空。

type Result struct {
    Count int      `json:",omitzero"`
    Tags  []string `json:",omitempty"`
    Note  *string  `json:",omitzero,omitempty"`
}

迁移到 v2 时尤其要检查旧代码里的 omitempty。v1 里它会把 false、0、nil 指针和空容器视为空；v2 默认按 JSON 表示判断，所以 false 和 0 不是 JSON 空值，字段可能重新出现在响应中。官方给出的迁移方向是：布尔值、数字、指针和接口如果原意是“Go 零值时省略”，改用 omitzero；只有希望兼容 v1 的旧省略语义时，才考虑 v2 的 legacy option。

按兼容目标落地 struct tag

普通查询响应可以这样写，数值 0 是无意义默认值时交给 omitzero；空列表是否保留，则根据客户端是否把“空”和“未返回”当成不同状态决定。

type UserView struct {
    ID     int      `json:"id,omitzero"`
    Active bool     `json:"active,omitzero"`
    Labels []string `json:"labels,omitempty"`
}

type UserPatch struct {
    Nickname *string `json:"nickname,omitzero"`
    Active   *bool   `json:"active,omitzero"`
}

UserPatch.Active == nil表示不改动，指向 false 表示明确关闭；这是单靠 omitempty放在 bool 上做不到的。注意标签只影响编码，解码时 JSON 没有该字段和传入 null 的差异，还需要由指针、原始请求或自定义解码策略共同处理。

用样例矩阵做回归

改标签前固定最少四组输入：字段缺失、显式 null、零值、非零值；集合字段再增加 nil slice 与空 slice。用同一份结构体分别调用当前使用的 v1 和目标 v2 编码器，保存输出差异，重点看布尔值、数字、指针和空容器。

cases := []UserPatch{
    {},
    {Active: new(bool)},
    {Nickname: new(string)},
}
for _, v := range cases {
    b, err := jsonv2.Marshal(v)
    if err != nil { log.Fatal(err) }
    fmt.Println(string(b))
}

最后把“未传、清空、设为零、保持空数组”写进接口说明和测试名称。这样后续换编码器或调整 tag 时，看到的是明确的契约差异，而不是客户端偶发的字段缺失。

相关问题

omitzero 能替代所有 omitempty 吗？不能。字符串、空数组、空对象若按 JSON 结果判断，仍应使用 omitempty；只有两者效果相同且目标是 Go 零值时，优先考虑 omitzero。

为什么用了指针仍然返回 null？因为 nil 指针本身会编码为 JSON null；需要让字段消失时，再加 omitzero 或 omitempty，并确认客户端是否接受缺失。

迁移 v2 只改 import 就够了吗？不够。至少回归 omitempty、大小写匹配、nil slice/map 和未知字段策略；这些都是 v1 与 v2 可能不同的语义边界。

参考：encoding/json/v2 官方文档、encoding/json 官方文档。