Go json/v2 与 json v1 迁移时的字段兼容清单

Go json/v2 迁移最容易误判的地方，是把“能编译”当成“字段兼容”。更稳妥的做法是先记录旧接口对 null、空数组、字段大小写和未知成员的约定，再用 DefaultOptionsV1 保住原行为，最后逐项切换 v2 语义。这样既能使用新 API，也不会让下游服务突然收到另一种 JSON。

先把字段兼容问题拆成四张清单

迁移前建议按字段逐项登记：JSON 名称、空值形态、数字是否用字符串承载、输入出现未知成员时的处理方式。v1 反序列化默认会做宽松的大小写匹配，v2 默认更严格；没有显式标签的 UserID、Userid 或外部的 userid，不应再靠“碰巧能匹配”维持契约。

用 DefaultOptionsV1 做第一阶段过渡

官方迁移路径允许在 v2 API 中传入 v1 默认选项。这样可以先替换调用入口，再把每个行为差异变成可观察、可回滚的改动。下面的示例只展示迁移边界，注释说明了兼容开关的作用；具体工程仍应固定工具链并运行自己的契约测试。

package main

import (
	jsonv1 "encoding/json" // 只借用 v1 的兼容选项集合
	"encoding/json/v2" // 使用 v2 的 Marshal API
	"fmt"
)

type Payload struct {
	UserID string   `json:"user_id"`
	Tags   []string `json:"tags"`
}

func main() {
	data := Payload{UserID: "u-7"} // nil Tags 用来观察 null/[] 的契约差异
	b, err := json.Marshal(data, jsonv1.DefaultOptionsV1()) // 先保持旧语义
	if err != nil {
		panic(err) // 示例直接终止；服务代码应返回带上下文的错误
	}
	fmt.Println(string(b))
}

如果项目仍依赖旧接口输出 "tags":null，可以在确认影响范围后使用 json.FormatNilSliceAsNull(true)；map 对应 json.FormatNilMapAsNull(true)。这两个选项只影响编码，不会替你修复反序列化时的字段命名问题。

标签和选项怎么选才不会误伤接口

对稳定的外部字段，优先在结构体上写完整名称，而不是全局打开大小写不敏感匹配。需要保留旧零值省略行为时，逐字段比较 omitempty 和 omitzero：前者按 JSON 表示是否为空判断，后者按 Go 零值或 IsZero 判断，时间、地址等有明确零值定义的类型尤其容易产生差异。

数字字段如果历史协议把数字放在字符串中，要检查 string 标签和 StringifyNumbers 的范围；未知字段则不要一开始就全部拒绝，先确认客户端是否会扩展成员，再对确实需要严格输入的入口启用 RejectUnknownMembers(true)。

type User struct {
	ID        string    `json:"id"`              // 固定外部名称，不依赖大小写猜测
	CreatedAt time.Time `json:"created_at,omitzero"` // 按 Go 零值决定是否省略
	Score     int64     `json:"score,string"`     // 保持协议中的数字字符串形式
}

双版本回归要覆盖输出和输入两条路径

迁移测试不要只断言“没有 error”。对同一组 fixture，分别比较编码后的关键字段，再把旧 JSON 交给 v2 解码，检查大小写、未知成员、null 与空集合，以及数字字符串。若字节顺序不是协议要求，比较解析后的结构；若下游签名或缓存键依赖原始字节，则必须保留确定性与字段顺序约定。

生产服务可以先让旧语义返回给调用方，同时用双调用方式报告 v1/v2 差异；差异稳定后，再把返回值切到 v2。这个阶段要记录“哪个字段、哪种输入、哪一个选项”造成变化，避免用一个全局兼容开关掩盖真实问题。

常见问题

只替换 import 就能完成迁移吗？

只能说明调用点可能通过编译，不能证明 JSON 契约不变。至少要回归字段大小写、nil 集合和省略规则。

什么时候用 MatchCaseInsensitiveNames？

它适合暂时兼容历史输入；对新接口更建议显式 JSON 标签，让协议名称不依赖 Go 字段名。

omitzero 能直接替换所有 omitempty 吗？

不能。两者判断标准不同，尤其是空 slice、空 map、空字符串和实现了 IsZero 的类型，要按接口约定逐项确认。

这份清单的完成标志，是每个字段都有明确的输入、输出和回滚策略。先保持 v1 语义，再用小范围选项切换，比一次性替换所有标签更容易定位兼容问题。