Go json omitempty 配合 IsZero 怎样控制自定义零值

在 encoding/json 中，单独写 omitempty 不会因为结构体实现了 IsZero() bool 就按自定义规则省略字段。需要用 omitzero 连接这套零值判断；如果同时写两种选项，满足“空”或“零”中的任意条件就会省略，并不是两者都满足才省略。

Go 官方地址：https://go.dev/。下面示例明确使用 encoding/json，不讨论 encoding/json/v2 的不同 omitempty 语义。omitzero 从 Go 1.24 引入，旧工具链不能靠添加标签获得相同行为，具体引入说明见 Go 1.24 发布说明。

先明确字段省略对调用方意味着什么

先区分“没有提供”和“明确提供零”。例如设置页面中的额度字段：用户没有填写，接口可以省略；用户明确设置为 0，则应保留 0。若把两者都当成可省略值，调用方就无法判断是沿用默认设置还是应用零值。

本文用 Limit 保存 Value 与 Set：Value 是额度，Set 表示是否明确提供。Limit.IsZero 返回 !Set。这是一种业务约定，不是 Go 自动理解了表单含义。让字段缺失有确定含义，比一味减少 JSON 字节更重要。

omitempty 不会按自定义 IsZero 省略结构体

encoding/json 的 omitempty 按自身的空值规则工作，包含 false、数字 0、nil 指针或接口，以及长度为零的数组、slice、map、字符串；结构体值不属于这组空值。即使 Limit.IsZero 返回 true，单独用 omitempty 的结构体字段仍然会保留。

参数规则见 json.Marshal 官方文档。不要仅看到字段仍然输出，就在 IsZero 里加入日志或修改状态；先确认字段标签与实际导入包。

用 omitzero 连接自定义零值规则

下面是可独立保存为 main.go 的原创示例。值接收者避免给这个简单值对象额外引入可寻址性与 nil 接收者问题。Set 标记不进入 JSON，字段是否出现由外层标签决定。

package main

import (
    "encoding/json"
    "fmt"
    "log"
)

type Limit struct {
    Value int  `json:"value"`
    Set   bool `json:"-"`
}

// IsZero 只判断业务上的“未提供”，不修改值。
func (l Limit) IsZero() bool {
    return !l.Set
}

type Payload struct {
    Legacy Limit `json:"legacy,omitempty"`
    Custom Limit `json:"custom,omitzero"`
}

func main() {
    // 两个字段采用相同输入，对照各自标签的省略语义。
    cases := []Limit{
        {},
        {Value: 0, Set: true},
        {Value: 18, Set: true},
    }
    for _, item := range cases {
        data, err := json.Marshal(Payload{Legacy: item, Custom: item})
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(string(data))
    }
}

按示例约定，预期内容如下；这是语义推导，不是本文的本机运行记录。

{"legacy":{"value":0}}
{"legacy":{"value":0},"custom":{"value":0}}
{"legacy":{"value":18},"custom":{"value":18}}

第一行中的 legacy 仍然存在，custom 因未提供而省略；第二行证明“显式零”可以被保留。第三行则保留有效额度。注意 Limit{Value:18, Set:false} 仍会被 omitzero 当成零值：既然规则选择 Set，就要保证构造逻辑维护这个标记。

同时使用两种标签时注意或关系

json:"custom,omitempty,omitzero" 表示空或零任一成立便省略。对于这里的 Limit 结构体，omitempty 自己不把它判为空，实际自定义判断仍来自 omitzero；没有必要为了“增强”效果而机械叠加标签。

对 slice，omitempty 的长度为零与 omitzero 的类型零值也不总是一回事。没有自定义方法时，非 nil 的空 slice 可以不是类型零值；同时加 omitempty 又会按长度为零省略它。若调用方需要区分缺失字段和空数组，叠加标签可能恰好破坏契约。

IsZero 不负责决定一个已保留字段怎样编码；它也不是 Unmarshal 的存在性记录。上面的 Set 被 json:"-" 忽略，不能直接反序列化后就期待它记录“用户提交过”。入站字段存在性需要单独的输入模型或自定义解码设计；此处只演示出站字段省略。

为零值、显式零与有效值保留回归

在项目回归中至少覆盖以下输入，判断 JSON 对象里是否存在对应键，而不只是比较字符串长度。

IsZero 应保持确定、无副作用，不用网络请求或修改接收者来判断零值。若这个类型被多个接口复用，增加 IsZero 会影响那些已经使用 omitzero 的字段；先确认所有调用方需要同一种零值含义。省略不代表数据非法，IsZero 也不替代业务校验。

IsZero 返回 false 就一定输出吗？

不一定。若还配置了 omitempty 且其空值条件成立，字段仍可能省略；此外 json:"-" 会直接忽略字段。

改成指针字段会更简单吗？

如果只需要区分未提供与有值，可以考虑 nil 与非 nil 的指针模型。非 nil 指针指向零值时，omitempty 不会仅因指向的值为零而省略；不要把指针模型和自定义零值规则混为一谈。

为什么本地生效，旧构建环境不生效？

检查实际编译工具链是否支持 omitzero，以及导入的是哪个 JSON 包。不要假设结构体标签里出现这个词就保证编码器认识它。