Go json.UnmarshalJSON omitempty 为什么不会隐藏零值结构体

给嵌套结构体加上 json:",omitempty"，结果里却还出现 "profile":{"name":""}，这不是 UnmarshalJSON 失效，而是把入站解析和出站编码混到了一起。默认的 encoding/json 中，omitempty 只在 Marshal 时判断一组“空值”；结构体本身不在这组旧语义里，所以零值结构体仍会被编码。

想让整个对象字段消失，最直接的表达是让字段成为 nil 指针；想保留“缺失、空对象、显式零值”三种状态，则应把它们当成 API 契约设计，而不是继续叠加标签。

先复现零值结构体仍被编码

先看一个最小模型。Profile 的 Name 是空字符串，但外层字段是值类型 struct：

package main

import (
    "encoding/json"
    "fmt"
)

type Profile struct {
    // 空字符串属于 omitempty 的空值候选。
    Name string `json:"name,omitempty"`
}

type Request struct {
    // Profile 是值类型 struct，不是 nil 指针。
    Profile Profile `json:"profile,omitempty"`
    Note    string  `json:"note,omitempty"`
}

func main() {
    body, err := json.Marshal(Request{})
    if err != nil {
        // 生产代码应保留编码错误，不要用空响应掩盖失败。
        panic(err)
    }
    fmt.Println(string(body))
    // 结果会包含 profile，而 note 会被省略。
}

这里真正被判断的是两个不同层次：Name 的空字符串可以省略，但外层 Profile 仍然是一个可编码的 struct。子字段都为空，不等于父对象在 v1 encoding/json 中自动变成“空值”。

拆开 UnmarshalJSON 与 omitempty 的职责

方法名相似，方向却相反。UnmarshalJSON 只在 JSON 输入解码到某个值时参与；omitempty 是 struct tag 的 Marshal 选项。给类型实现自定义解析方法，不会改变外层字段在编码阶段的空值判定。

type Profile struct {
    Name string `json:"name,omitempty"`
}

// UnmarshalJSON 只处理输入，不负责决定 profile 是否出现在输出中。
func (p *Profile) UnmarshalJSON(data []byte) error {
    type plainProfile Profile // 换一个类型，避免再次调用本方法递归。
    var decoded plainProfile
    if err := json.Unmarshal(data, &decoded); err != nil {
        // 输入不是合法 Profile 时，把解析错误交给调用方。
        return err
    }
    *p = Profile(decoded)
    return nil
}

因此，排查时先问“问题出现在输入还是输出”。输入阶段看 JSON 是否触发了 UnmarshalJSON；输出阶段看字段的实际 Go 类型、是否为 nil，以及标签使用的是哪种语义。不要期待 UnmarshalJSON 把一个值类型 struct 变成可省略的 nil。

按 v1 encoding/json 的空值规则定位结构体边界

默认 encoding/json 的 omitempty 会跳过 false、数字 0、nil 指针、nil interface，以及长度为 0 的数组、切片、map 和 string。这个列表没有普通 struct。标准库编码器在遍历字段时先做空值判断，值类型 struct 不会因为内部字段全部是零值而自动递归折叠。

这也解释了为什么“给 Profile 增加 IsZero”并不能直接改变默认 v1 omitempty 的行为：标签默认看的不是任意自定义零值方法，而是它支持的空值类型集合。不要把其他编码语义或实验性 JSON v2 选项混用到这段默认行为的结论里。

用指针表达可选对象并比较输出

如果接口约定是“没有资料时不发送 profile”，把字段声明成指针更贴近语义：

type Request struct {
    // nil 表示字段不存在；非 nil 表示调用方选择发送一个对象。
    Profile *Profile `json:"profile,omitempty"`
}

missing := Request{}
empty := Request{Profile: &Profile{}}

// missing 可得到 {}；empty 仍会得到 {"profile":{"name":""}}。
// 指针解决的是“字段是否存在”，不是“对象内部是否全为零值”。

这里有一个容易忽略的边界：非 nil 指针指向零值结构体时，字段仍然会输出。若业务还要把空对象也隐藏，就在组装响应时把“空 Profile”规范化为 nil，或者为专门的响应类型实现明确的 MarshalJSON。不要通过修改输入解析方法来承担这个职责。

根据 API 语义选择长期修复方案

最终应该先确定客户端是否区分三种状态，再选写法：

• 只需要“有或无”：使用 *Profile，无资料设为 nil。
• 需要表达“空对象”：保留非 nil 指针或值类型，并接受 {} / 空字段是有效结果。
• 需要“全零对象也不输出”：在响应组装阶段统一归一化，或让响应模型的 MarshalJSON 明确控制输出。

复查时可以按“输入 JSON → Go 值 → 输出 JSON”画出三段边界：输入是否触发 UnmarshalJSON，模型字段是否为 nil，最终才看 omitempty 能否命中。这样定位出来的是数据契约问题，而不是继续试错标签拼写。

相关问题

omitempty 会影响 json.Unmarshal 吗？

不会。它是 Marshal 阶段的字段选项，输入 JSON 缺少字段时，解码器不会因为这个标签自动清理已有值。

为什么 nil 指针能省略，空指针指向的 struct 却不能？

因为标签判断的是指针本身是否为 nil。非 nil 指针仍代表一个存在的对象，指向对象内部是否全为零值是另一层语义。

自定义 MarshalJSON 能不能解决空对象问题？

能，但应把规则放在响应模型边界，并为缺失、空对象和显式零值写清楚测试；只靠外层值 struct 的 omitempty 不够。