jsonv2兼容旧encodingjson代码

如果旧项目已经大量使用 encoding/json，迁移到 JSON v2 不需要一次性重写。Go 1.27 提供了 encoding/json/v2 和 encoding/json/jsontext，同时继续支持原来的 encoding/json。更稳妥的做法是：先让 v2 调用携带 DefaultOptionsV1()，确认业务输出稳定后，再逐项打开 v2 行为。

官方资料：https://go.dev/doc/jsonv2-migration

先判断：旧 encoding/json 代码要不要改

如果目标只是升级 Go 版本，通常不需要因为 JSON v2 立刻改掉旧导入。官方说明中，原 encoding/json 会继续支持，且其实现已经在内部使用 v2 代码，但仍保留 v1 语义。也就是说，“升级工具链”和“迁移调用方”是两件事，可以拆开安排。

真正需要评估的是行为依赖：下游是否依赖 nil 切片编码为 null，输入是否可能包含重复对象键或非法 UTF-8，结构体字段是否依赖大小写不敏感匹配，或者测试是否把错误文本、JSON 字节顺序当成契约。只要这些边界没有确认，就不要把导入路径替换当成完成迁移。

用 DefaultOptionsV1 先把行为锁住

迁移的第一步不是立刻接受全部默认变化，而是把调用点换成 v2 API，同时传入旧语义选项。DefaultOptionsV1() 位于原 encoding/json 包，返回的选项可以传给 v2 的 Marshal 和 Unmarshal。

package main

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

type Pet struct {
	Name      string
	Nicknames []string
}

func main() {
	pets := []Pet{
		{Name: "Oliver", Nicknames: []string{"Ollie"}},
		{Name: "Remi"}, // nil 切片先按 v1 语义处理
	}

	// 先切换 API，不同时切换所有 JSON 行为。
	b, err := jsonv2.Marshal(pets, json.DefaultOptionsV1())
	if err != nil {
		log.Fatal(err) // 发布前让编码错误显式失败
	}
	fmt.Println(string(b))
}

这个写法的价值是把“调用路径变化”和“数据格式变化”分离。后续如果确认下游可以接受 nil 切片输出为空数组，就只移除对应的 v1 兼容选项，或者在保留其他 v1 行为的同时覆盖某一项：

import (
	jsonv1 "encoding/json"
	jsontext "encoding/json/jsontext"
	jsonv2 "encoding/json/v2"
)

func decode(data []byte, out *Profile) error {
	// 先保留旧语义，再明确禁止重复键，缩小单次变更范围。
	return jsonv2.Unmarshal(
		data,
		out,
		jsonv1.DefaultOptionsV1(),
		jsontext.AllowDuplicateNames(false),
	)
}

再逐项打开 v2 行为

v2 的默认值更严格、更接近可互操作的 JSON 处理。常见差异包括：非法 UTF-8 默认报错，重复对象键默认报错，结构体字段名默认大小写敏感，nil 切片和 nil map 默认编码为空数组或空对象，omitempty 的“空”定义也发生了变化。

不要把这些变化混成一个“大迁移”。可以先保留 DefaultOptionsV1()，每次只覆盖一个选项，并为对应输入准备回归样例。例如，字段命名兼容可以使用 MatchCaseInsensitiveNames(true)；允许旧数据中的非法 UTF-8 则使用 jsontext.AllowInvalidUTF8(true)。选项越具体，出现差异时越容易知道该回退哪一项。

还要留意自定义方法。v2 支持旧的 MarshalJSON 方法，也提供 MarshalJSONTo 等新接口，因此依赖包不必因为使用不同版本而强制统一。迁移时应把自定义 marshaler、结构体标签和接口值一起列入边界样例，不要只测普通结构体。

哪些代码要重点回归

回归重点应放在协议边界，而不是只跑一组正常 JSON。至少覆盖以下数据：

• nil 切片、nil map、空切片和空 map，分别检查 null、[]、{} 的外部契约。
• 字段名大小写不同、历史别名和带 json 标签的结构体，确认解码目标没有改变。
• 重复对象键、非法 UTF-8、未知字段和大整数，确认服务是拒绝、保留还是兼容。
• 自定义 MarshalJSON、UnmarshalJSON 以及接口中的指针值，确认方法调用语义。
• 错误处理代码，尤其是只比较完整错误字符串的测试；升级后错误文本可能不同。

如果服务不能立即改变线上输出，可以使用官方迁移指南提到的 jsonsplit 做差异观测：同时计算 v1 和 v2，但继续返回 v1 结果，再记录差异。它会增加编码成本，因此应按采样比例使用，并把它当成迁移观测工具，而不是永久默认路径。

迁移清单与常见问题

推荐顺序：保留旧调用作为基线 → 为 v2 调用加入 DefaultOptionsV1() → 补齐边界样例 → 一次只切换一个选项 → 观察协议差异 → 再删除不需要的兼容项。

旧 encoding/json 会被废弃吗？不会。官方承诺继续支持 v1，项目可以长期保留旧 API。迁移 v2 的主要收益是更清晰的选项模型和更严格的默认值，不是因为旧代码马上不能编译。

能不能用 GOEXPERIMENT=nojsonv2 一直回退？它适合排查升级后的兼容问题，但官方说明预计未来移除，不应当作为长期迁移方案。应记录触发差异的输入，并回到选项或调用点解决。

一句话总结：兼容旧 encoding/json 代码的关键是先保持语义、再切换行为。用 DefaultOptionsV1() 建立过渡层，再按数据契约逐项启用 v2，迁移会比一次替换导入路径更可控。