Go 1.27 encoding/json/v2 的 omitempty 行为迁移先看什么

Go 1.27 已经把 encoding/json/v2 带入标准库，同时让原有 encoding/json 由 v2 实现支撑，但继续保持 v1 API 的兼容语义。真正需要提前检查的，不是所有 omitempty 都要改，而是它在 v2 中判断的“空”变了：布尔值 false 和数字 0 会按 JSON 值保留。迁移时，先区分“业务零值”与“JSON 空值”，再决定标签。

官方资料：https://go.dev/doc/go1.27

先确认变化：omitempty 省略的是哪一种“空”

Go 1.27 的发布说明把这次变化拆成两层：新增的 encoding/json/v2 提供可配置的 JSON API；原有 encoding/json 仍然支持，且默认行为保持兼容。也就是说，升级 Go 编译器不等于现有接口立刻改成 v2 的 omitempty 语义，但新写的 v2 调用和迁移中的显式选项必须按新规则检查。

v1 把 false、0、nil 指针、nil 接口以及空数组、切片、映射、字符串视为可省略的 Go 空值。v2 的 omitempty 则关注最终 JSON 是否是 null、空字符串、空对象或空数组。于是布尔值和数字的“零”并不自动等于 JSON 空值。

从字段类型开始排查，而不是全局替换标签

先在结构体中筛出带 omitempty 的字段，再按“值类型、业务含义、对外契约”三列记录。字段是否能省略，应该由接口约定决定，而不是由标签名称决定。

例如，状态字段的 false 可能表示“明确关闭”，就不应因为省略而让接收方误判；重试次数为 0 也可能是业务结果。相反，备注为空通常可以省略。这里先写出业务语义，才能避免把所有标签机械地替换成另一种标签。

迁移落地：先改标签，再加兼容开关

如果字段的要求确实是“Go 零值不出现在 JSON 中”，可以把意图写进标签。下面的示例只让零值布尔和整数省略，同时让空集合按 JSON 空值规则省略：

package main

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

type Result struct {
    Enabled bool              `json:"enabled,omitzero"` // 业务上未启用时不输出 false
    Retries int               `json:"retries,omitzero"` // 0 表示未设置时省略
    Note    string            `json:"note,omitempty"`  // 空字符串编码为空 JSON 值
    Labels  map[string]string `json:"labels,omitempty"` // 空对象不进入响应
}

func main() {
    data, err := json.Marshal(Result{}) // 用 v2 直接观察字段标签表达的意图
    if err != nil {
        panic(err) // 示例中直接终止，生产代码应返回带上下文的错误
    }
    fmt.Println(string(data)) // 重点检查字段是否符合对外 JSON 契约
}

如果项目需要分阶段切换，可以在仍使用 omitempty 的调用点传入 json.OmitEmptyWithLegacySemantics(true)，临时恢复 v1 的“Go 空值”判断。这个选项只影响 marshaling，不会改变 unmarshaling；它适合做灰度和对比，不应替代字段语义整理。

data, err := json.Marshal(payload,
    json.OmitEmptyWithLegacySemantics(true), // 迁移过渡期保留 v1 的 omitempty 语义
)
if err != nil {
    return err // 调用方应保留编码失败，不能静默发送半成品响应
}

最后用 JSON 契约测试挡住回归

迁移的验收点不是“代码能编译”，而是关键输入的字段集合和字段值没有悄悄改变。至少为零值、非零值、空集合、nil 指针和指向零值的指针各准备一个样例；对外 API 还应检查旧客户端是否依赖某个字段始终出现。

func TestResultJSONContract(t *testing.T) {
    got, err := json.Marshal(Result{}) // 固定零值样例，锁定字段出现规则
    if err != nil {
        t.Fatal(err) // 测试失败时保留原始编码错误
    }
    want := `{}` // 示例契约需按实际产品约定调整
    if string(got) != want {
        t.Fatalf("json contract changed: got %s want %s", got, want) // 变化应显式暴露
    }
}

真实项目中不要照抄这个 want：如果接口约定空字符串也必须省略，期望值就应改成对应的 JSON；如果启用了兼容选项，也应为兼容路径单独命名测试。必要时先用 GOEXPERIMENT=nojsonv2 go test ./... 做故障定位，确认是否来自新实现，再决定修标签还是保留兼容策略。该退出开关只是过渡手段，Go 官方说明预计未来移除。

常见问题

Go 1.27 升级后，所有 encoding/json 代码都必须迁移吗？

不需要。原有 encoding/json API 继续支持，且默认保留 v1 行为；只有主动使用 encoding/json/v2 或调整选项时，才应按 v2 语义逐项检查。

omitzero 能完全替代 omitempty 吗？

不能。omitzero表达 Go 零值，omitempty表达编码后的 JSON 空值；字符串、切片、映射等场景可能相近，但业务意图不同，仍要按字段契约选择。

为什么不能只跑一遍 go test？

普通单元测试可能没有覆盖零值和空集合的字段组合。迁移至少要补齐代表性 JSON 样例，并检查字段“出现/消失”是否影响客户端兼容。