当前位置：首页 > 文章列表 > Golang > Go教程 > jsonv2兼容旧encodingjson代码

jsonv2兼容旧encodingjson代码

来源：17golang原创 2026-11-15 03:11:53 0浏览收藏

如果旧项目已经大量使用 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 字节顺序当成契约。只要这些边界没有确认，就不要把导入路径替换当成完成迁移。

场景	建议	原因
只升级 Go，暂不改变行为	保留 `encoding/json`	旧 API 仍受支持
新代码希望使用 v2 选项	引入 `encoding/json/v2`	可以显式配置语义
旧服务风险较高	v2 + `DefaultOptionsV1()`	先锁住旧行为，再小步切换

旧 encoding/json、DefaultOptionsV1 和 encoding/json/v2 的兼容关系结构说明图 — 图1：兼容关系说明图，展示旧调用、v1 兼容选项与 v2 API 的静态边界；这不是运行截图。

用 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、结构体标签和接口值一起列入边界样例，不要只测普通结构体。