Go 1.27 json/v2 怎样理解 JSON 迁移

Go 1.27 带来的 encoding/json/v2，最容易让人误判的地方是：把导入路径从 encoding/json 改成 encoding/json/v2 后，代码可能照样编译，但 JSON 的行为并不一定完全相同。迁移真正要处理的是默认语义变化，而不是把包名替换一遍。

官方地址：https://go.dev/doc/jsonv2-migration

Go 1.27 发布说明：https://go.dev/doc/go1.27

v2 包文档：https://pkg.go.dev/encoding/json/v2

如果旧系统依赖 JSON 的具体字节形态、错误边界或字段兼容行为，先把 v1 与 v2 的差异找出来，再决定是否切换默认语义。Go 1.27 并没有要求所有项目立即迁移，原来的 encoding/json 仍受 Go 兼容承诺保护。

先看影响面：新包带来了什么

Go 1.27 正式提供 encoding/json/v2 和更底层的 encoding/json/jsontext。v2 的 API 仍然保留熟悉的 Marshal、Unmarshal，同时增加面向 io.Writer、io.Reader 和 JSON token 流的能力。与此同时，旧的 encoding/json 由 v2 实现支撑，但继续保持 v1 的默认行为。

因此，新闻里的“JSON 迁移”不是一次强制替换，而是一次语义选择：新代码可以直接使用 v2，存量服务则要先判断下游是否把 null、错误文本或字段名行为当成了接口契约。

症状复盘：为什么只换 import 也会出问题

最直观的触发条件是 nil 切片。下面这个结构体没有给 Nicknames 赋值，v1 默认会把它编码成 null；v2 默认则会把 nil 切片编码成空数组。

package main

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

type Pet struct {
	Name      string
	Nicknames []string
}

func main() {
	// 故意保留 nil 切片，用来观察 v2 的默认表示。
	pet := Pet{Name: "Remi"}
	b, err := jsonv2.Marshal(pet)
	if err != nil {
		// 生产代码应把编码错误返回给调用方，而不是静默忽略。
		panic(err)
	}
	fmt.Println(string(b))
}

迁移前后都能编译，并不等于接口输出不变。除了 nil 切片和 nil map，v2 默认还会拒绝 JSON 字符串中的非法 UTF-8、拒绝对象中的重复成员名，并更早报告某些结构体标签错误。若客户端只接受 null，或者历史数据允许重复成员名，切换就可能表现为接口回归。

根因定位：API 差异小，行为差异才是重点

Go 官方迁移指南把难点分成两层：简单编解码的 API 迁移通常只是换导入路径，真正需要排查的是序列化和反序列化语义。换句话说，编译器能回答“名字是否存在”，却不能替你判断“下游是否依赖旧 JSON”。

这也是为什么“升级成功”不能只看编译和单元测试数量。要把对外 JSON 视为协议，至少比较代表性响应、异常输入和结构体标签边界。

修复动作：按风险选择三条迁移路径

小型工具或新服务可以直接切换到 encoding/json/v2，然后围绕输出快照和异常输入补测试。旧系统风险较高时，官方建议先使用 v2 API 加上 jsonv1.DefaultOptionsV1()，让调用点先换过来，再逐个打开 v2 行为。

package main

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

type Pet struct {
	Name      string
	Nicknames []string
}

func encodeWithLegacyDefaults(p Pet) ([]byte, error) {
	// 先使用 v1 兼容选项，降低一次性改变输出的风险。
	return jsonv2.Marshal(p, jsonv1.DefaultOptionsV1())
}

第二条路径是按选项迁移：保留大部分 v1 语义，只对已经确认安全的差异打开 v2 行为。第三条路径适合生产服务，用 github.com/go-json-experiment/jsonsplit 同时比较 v1 与 v2，继续返回 v1 结果，并把差异写入日志或指标。它会增加编解码成本，所以更适合采样或阶段性使用。

防复发清单：迁移完成后复查什么

第一，给对外响应保留关键 JSON 快照，尤其是 nil 切片、nil map、时间字段和自定义 Marshaler。第二，为重复成员名、非法 UTF-8、未知字段和错误标签准备输入样本。第三，检查结构体标签中的 inline 等迁移变化；Go 1.27 的 v2 语境中，相关标签能力有调整，不能只依赖旧版本的字符串搜索。

最后，把回滚边界写进发布说明。Go 1.27 提供 GOEXPERIMENT=nojsonv2 作为遇到兼容问题时的临时退路，但它不是替代测试的长期方案，而且官方说明预计未来版本会移除这个开关。

• 新服务：直接使用 v2，先覆盖协议快照和异常输入。
• 老服务：先用 DefaultOptionsV1，按差异逐项打开。
• 复杂生产链路：阶段性使用 jsonsplit，记录 v1/v2 差异后再切换。

常见问题

是不是所有项目都必须迁移到 json/v2？

不是。旧的 encoding/json 会继续保留，Go 1.27 的兼容承诺也仍然适用。是否迁移取决于项目是否需要 v2 的 API 和更严格默认值，以及团队是否能承担协议回归成本。

只比较 Marshal 的结果够不够？

不够。还要覆盖 Unmarshal 的非法输入、重复成员名、非法 UTF-8、未知字段和结构体标签错误，因为 v2 的变化同时发生在编码和解码边界。

DefaultOptionsV1 是永久兼容层吗？

它更适合作为渐进迁移的控制手段。先用兼容默认值稳定调用点，再用测试和差异记录逐项采用 v2 语义，比永久把所有代码锁在旧行为上更容易完成收敛。

这次 Go 1.27 的 JSON 变化，最值得记住的是“编译通过只是迁移的起点”。先找出接口真正依赖的行为，再选择直接切换、选项控制或差异对比，才能把一次版本升级变成可回滚、可复查的工程变更。