Go encoding/json omitempty 对零值字段的输出边界

Go 结构体标签里的 omitempty 只影响编码输出，不会把“零值”笼统地全部删除。标准 encoding/json 把 false、数值 0、空字符串、长度为 0 的数组/切片/映射，以及 nil 指针和 nil 接口视为空值；字段命中这些条件时，JSON 对象里不会出现这个键。反过来，非 nil 的结构体即使内部字段全是零，也不会因为 omitempty 自动消失。

官方资料：https://pkg.go.dev/encoding/json

omitempty 的规则先按 Go 类型拆开

可以把 omitempty 看成字段级过滤器，而不是结构体级过滤器。它在准备写入字段名之前检查当前字段的类型和值：布尔值的 false、整数或浮点数的 0、字符串 ""、长度为零的数组、切片、映射和字符串，以及 nil 指针或 nil 接口，都会被跳过。

这里有两个容易混淆的词：Go 零值和 JSON 空值。数组的判断看长度，不看每个元素；所以 [2]int{0, 0} 仍然是一个有两个元素的数组。结构体也没有被列入这组空值，time.Time 这类值即便表示“未设置时间”，也不会仅靠 omitempty 消失。

用一组字段看清零值、空集合和 nil 的差别

下面这个示例故意把常见类型放在同一个结构体里。代码中的注释说明了字段意图，输出只展示编码结果，不把它描述成某台机器上的运行证据。

package main

import (
    "encoding/json"
    "fmt"
)

type Payload struct {
    Enabled bool           `json:"enabled,omitempty"` // false 表示空值，会省略键
    Limit   int            `json:"limit,omitempty"`   // 0 表示空值，会省略键
    Note    string         `json:"note,omitempty"`    // 空字符串会省略键
    Tags    []string       `json:"tags,omitempty"`    // nil 和空切片长度都为 0
    Labels  map[string]int `json:"labels,omitempty"`  // nil 和空映射长度都为 0
    Pair    [2]int         `json:"pair,omitempty"`    // 长度为 2，不会因元素为 0 而省略
    Retry   *int           `json:"retry,omitempty"`   // nil 指针省略，非 nil 指针保留值
}

func main() {
    retry := 0
    value := Payload{Pair: [2]int{0, 0}, Retry: &retry}
    encoded, err := json.Marshal(value)
    if err != nil {
        panic(err) // 示例中直接终止；服务代码应返回或记录错误
    }
    fmt.Println(string(encoded)) // 结果会保留 pair 和 retry:0
}

这个对象的关键结果是：pair 会保留，因为数组长度是 2；retry 也会保留，因为指针本身非 nil，即使它指向的整数是 0。Tags 和 Labels 则不论是 nil 还是空集合，都满足长度为零的条件。

可选 API 字段要区分“没传”与“传了零”

如果接口把 false、0 或空字符串当作有效的明确选择，就不要直接给这些标量加 omitempty。例如分页请求里，limit=0 可能代表“使用服务端默认值”，也可能代表调用方明确要求零条；这两个语义不能靠一个 int 字段猜出来。

更稳妥的做法是把可选标量改成指针：nil 表示未提供，指向 false 或 0 则表示调用方明确传入。对外响应也要先约定是缺失、null 还是零值，再决定是否加标签。指针不是为了让 JSON 更短，而是为了把“存在性”纳入数据模型。

结构体、自定义编码与版本语义的边界

最常见的误判是给一个结构体字段加上 omitempty，期待它在内部全为零时被省略。标准编码器不会按“内部是否全空”替结构体做业务判断；如果确实要控制它是否出现，应使用 nil 指针包裹，或实现明确的自定义编码策略。

还要留意自定义 MarshalJSON：它可能改变字段最终的 JSON 形态，调用方看到的空对象、空数组或字符串不一定对应原始 Go 值。当前 Go 官方资料还列出了 omitzero，它按 Go 零值或 IsZero() bool 方法判断，与 omitempty 的字段空值语义不同。项目若要采用它，应先用目标 Go 版本做编译与接口回归。

常见问题

空切片和 nil 切片会得到不同的 JSON 吗？

在标准 encoding/json 的 omitempty 判断中，两者长度都为 0，因此字段都会被省略。去掉标签后，nil 切片通常编码为 null，空切片编码为 []，这时接口契约就必须明确区分。

结构体字段为什么没有像 int 一样被省略？

结构体不属于 omitempty 定义的空值集合。若业务上要让它可选，用 *Struct，以 nil 表示不存在；不要依赖内部字段恰好都是零。

什么时候不应该使用 omitempty？

当调用方需要收到 false、0、空字符串、空数组或空对象来表达明确状态时，不要为了缩短 JSON 而省略它。先写清“缺失”和“空值”的含义，再选择普通字段、指针或自定义编码。

落地时可以把字段逐一放进上面的四列检查表，并为“键缺失、null、空集合、明确零值”各写一个断言。这样排查输出异常时，先确认标签语义，再检查自定义编码和接口约定，通常比反复改结构体字段更快。