encoding/json/v2 的 omitzero 为什么没有省略字段

omitzero 没有省略字段，通常不是 encoding/json/v2 失效，而是字段并不满足它的判定条件。它只在编码时检查：类型若有 IsZero() bool 就采用该方法，否则按 Go 语言的零值判断。最常见的两个原因是标签漏了逗号，或者把非 nil 的空切片、空 map 当成了 Go 零值。

先看标签是否真的声明了 omitzero

结构体标签的第一段是 JSON 字段名，逗号后才是选项。因此下面两种写法含义完全不同：

type Wrong struct {
	// 这里把 omitzero 设成了 JSON 字段名，没有启用省略选项。
	Name string `json:"omitzero"`
}

type Right struct {
	// 保留默认字段名，并启用 omitzero。
	Name string `json:",omitzero"`
	// 同时指定 JSON 名称与省略选项。
	Count int `json:"count,omitzero"`
}

如果输出里出现 "omitzero":""，先不要排查零值算法；这几乎直接说明标签被解析成了字段名。需要自定义字段名时写成 json:"name,omitzero"，不改名时写成 json:",omitzero"。

最常见的误区：空切片不是切片零值

omitzero 的“zero”指 Go 零值，不是“长度为 0”，也不是“编码成空 JSON”。切片和 map 的零值是 nil；通过字面量或 make 创建的空容器已经是非 nil 值，所以仍会被保留。

package main

import (
	"fmt"

	json "encoding/json/v2"
)

type Payload struct {
	Name string            `json:"name,omitzero"`
	Tags []string          `json:"tags,omitzero"`
	Meta map[string]string `json:"meta,omitzero"`
}

func main() {
	v := Payload{
		// 空字符串是 string 零值，因此会省略。
		Name: "",
		// 两个容器长度为 0，但它们都不是 nil。
		Tags: []string{},
		Meta: map[string]string{},
	}
	b, err := json.Marshal(v)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // tags 与 meta 仍会保留。
}

若业务需求是“空容器也省略”，使用 omitempty 更贴切，因为它按编码后的 JSON 空值判断。也可以同时写 json:"tags,omitzero,omitempty"；两个条件中任意一个成立，字段就会省略。

结构体是否为空，要看零值或 IsZero

对于结构体，不能用“所有字段看起来都没业务数据”替代零值判断。没有自定义方法时，omitzero 按该 Go 类型的零值比较；如果类型提供了签名准确的 IsZero() bool，则以方法结果为准。这也是 time.Time 等类型能表达自身空值语义的原因。

type RetryWindow struct {
	Seconds int
}

// IsZero 把非正数都定义为业务上的“未配置”。
func (w RetryWindow) IsZero() bool {
	return w.Seconds 

排查自定义类型时，确认方法名、参数和返回值完全是 IsZero() bool，并直接检查它对当前值返回什么。若方法返回 false，字段保留就是预期行为；omitzero 不会再替你猜测“业务上是否为空”。

接口和指针要检查外层值是否为 nil

指针的零值是 nil，但“指向零值的非 nil 指针”仍然是一个非零指针。接口也一样：只有接口本身为 nil 才是接口零值；接口里装着一个具体值后，外层接口就不再是 nil。看到字段保留时，应先查看结构体字段本身，而不是只看它包裹的具体值。

不要在 Unmarshal 路径等待 omitzero 生效

omitzero 描述的是“编码输出时是否写出字段”。它对解码没有作用：输入 JSON 中有字段，Unmarshal 仍会按正常规则写入目标值；输入中没有字段，目标字段是否保留旧值也由解码规则和调用方式决定。

如果希望一个结构体的所有零值字段都采用同一策略，可以在 Marshal 时传入 json.OmitZeroStructFields(true)。它相当于为所有字段统一启用 omitzero，但同样只作用于编码，不会把空切片自动解释成 nil。

// 全局选项适合统一策略；单个字段仍可用标签表达局部意图。
b, err := json.Marshal(value, json.OmitZeroStructFields(true))
if err != nil {
	return err
}
_ = b

按这张清单定位未省略字段

1. 先看标签：是否写成 json:",omitzero" 或 json:"name,omitzero"。
2. 再看实际值：切片和 map 是 nil，还是长度为 0 的非 nil 容器。
3. 再看外层类型：指针或接口本身是否为 nil。
4. 检查自定义类型：是否存在签名准确的 IsZero() bool，当前值返回什么。
5. 确认调用方向：问题发生在 Marshal，而不是 Unmarshal。
6. 确认需求：要省略 Go 零值选 omitzero；要省略 JSON 空值选 omitempty。

官方文档对两者的边界很明确：omitzero 基于 Go 类型系统，omitempty 基于编码后的 JSON 类型系统。排障时只要把“标签是否生效”和“当前值属于哪一种空”分开，通常不需要改序列化器。

相关问题

为什么 json:"omitzero" 没有效果？

因为它把 omitzero 当作 JSON 字段名。启用选项要写成 json:",omitzero" 或 json:"字段名,omitzero"。

空切片怎样让 omitzero 省略？

让字段保持 nil，或改用 omitempty。非 nil 的 []T{} 不是切片零值。

omitzero 和 omitempty 能一起写吗？

可以。两者同时存在时，只要任意一个省略条件成立，字段就会被省略。

资料依据在哪里？

可查看 encoding/json/v2 官方包文档以及 Go 1.27 发布说明。