Go1.27升级后json/v2怎么安全迁

Go 1.27.0 已于 2026-08-19 GA（发布说明见 go.dev/blog/go1.27）。本版本正式提供 encoding/json/v2 与 encoding/json/jsontext；与此同时，官方 jsonv2-migration 说得很清楚------you don't have to ：encoding/json 不会消失（Go 1 兼容承诺）。v1 包现在由 v2 实现兜底，编解码行为保留，错误文案可能变。

常见误判：一看到 json/v2 就全仓改 import，编译过了，下游却吃到 null→[]、字段省略行为变了。本稿只谈：升到 1.27.x 之后，怎么安全迁到 v2 API------先 DefaultOptionsV1 锁行为，再逐项放开；以及构建期 GOEXPERIMENT=nojsonv2 该怎么理解 。同系列 Green Tea 默认 GC 验收见《Go1.26升级后Green Tea成默认GC怎么验》；本稿不展开 GC / goroutine 泄漏主线。核对补丁线时可见 go1.27.2（2026-10-08） 含 encoding/json / encoding/json/v2 修复------勿把补丁日当成 GA。

1. 痛点：改 import 往往能编过，行为却可能变了

三类常见混乱：

以为必须立刻全站迁完------官方明确可以不迁；新代码鼓励用 v2，不等于旧路径作废。
把 DefaultOptionsV1 写进 encoding/json/v2 ------该符号在 encoding/json （别名常写成 jsonv1），不在 v2 包。
把 GOEXPERIMENT=nojsonv2 理解成「别用 v2 API」 ------它管的是 v1 包背后的实现切换，不是禁止 import "encoding/json/v2"。

改成 import "encoding/json/v2" 后，调用可带 Options。v2 默认更严：nil 切片、omitempty、非法 UTF-8、重复 object name，都可能和旧 v1 不一致。安全迁不是「一次改干净」，而是 先对齐行为，再渐进放开 ：先给 v2 调用挂上 DefaultOptionsV1，确认与旧 encoding/json 等价，再谈接不接受更严默认。

2. 事实边界：可不迁；v1 永续；v2 是可选升级轴

先钉口径（go.dev/doc/go1.27 §New encoding/json/v2；jsonv2-migration）：

encoding/json 永续：不会删除、不会要求你必须迁走。
v1 现由 v2 实现兜底 ：Marshal / Unmarshal 行为保留；错误文本可能不同。
新代码可用 v2：更明确的 Options、更严默认；与 v1 可互操作（自定义 marshaler、新 tag 等，细节见官方迁移文）。
安全第一步 ：callsites 改成 v2 API，但传入 encoding/json.DefaultOptionsV1() ，使这次调用语义等价于旧 encoding/json.Marshal / Unmarshal。

官方示例形态（摘自迁移文档思路，包别名按官方习惯）：

go 复制代码

package main

import (
	"fmt"

	jsonv1 "encoding/json"
	"encoding/json/v2"
)

type Pet struct {
	Name       string
	Nicknames  []string
	Age        int `json:",omitempty"`
}

func main() {
	p := Pet{Name: "Remi", Nicknames: nil, Age: 0}

	// 安全第一步：v2 API + v1 默认 Options → 行为对齐旧 encoding/json
	b, err := json.Marshal(p, jsonv1.DefaultOptionsV1())
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b))
	// 在 DefaultOptionsV1 下，nil 切片仍编码为 JSON null（对齐 v1）
}

记住一句：DefaultOptionsV1 在 encoding/json，传给 v2 的 json.Marshal / json.Unmarshal 。别写成 json/v2.DefaultOptionsV1------那个包里没有这个符号。

3. 行为差：先盯 4 条高信号

完整差异见 jsonv2-migration 与 pkg.go.dev/encoding/json「Migrating to v2」。升级时先盯下面四条（官方明文）：

点	v1 常见观测	v2 默认	迁时注意
nil slice / map	JSON `null`	`[]` / `{}`	下游若用 `== null` 判空会踩坑
`omitempty`	旧语义	v2 重定义为「编码成空 JSON 值则省略」	bool / number / pointer / interface 上旧用法应迁 `omitzero`（v1/v2 均支持）
invalid UTF-8	静默替换为 U+FFFD	返回 error	脏数据路径要补错误处理
duplicate object names	允许	返回 error	对端若发重复键，解析会失败

可选第五条：部分结构错误 / 坏 tag，v1 不报、v2 运行时报错------排障时别当成「依赖坏了」。

omitempty → omitzero 最容易写错。官方：bool / number / pointer / interface 上的旧 omitempty 应改成 omitzero。字符串、切片等「空集合」场景仍可用 omitempty；别整表盲换成 omitzero，按类型对照文档改。

go 复制代码

package main

import (
	"fmt"

	jsonv1 "encoding/json"
	"encoding/json/v2"
)

// 演示：bool/number 上旧 omitempty 习惯，迁 v2 时改 omitzero
type Flags struct {
	Enabled bool    `json:"enabled,omitzero"`
	Count   int     `json:"count,omitzero"`
	Label   *string `json:"label,omitzero"`
}

func main() {
	var f Flags // zero values
	b, err := json.Marshal(f, jsonv1.DefaultOptionsV1())
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b))

	// 确认行为后再逐项去掉 DefaultOptionsV1、改用纯 v2 默认
	b2, err := json.Marshal(f)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b2))
}

nil 切片可按官方 Pet/Nicknames 思路自测：同一结构体，先 DefaultOptionsV1 看是否仍为 null，再纯 v2 看是否变成 []。Diff 写进升级报告，比口头「大概兼容」靠谱。

4. 怎么验收：同一结构体跑两组编码

别只靠「编译通过」。同一 DTO 跑两组输出，Diff 贴进报告：

对齐组 ：json.Marshal(v, jsonv1.DefaultOptionsV1()) ------ 期望与旧 encoding/json 一致（nil 切片仍为 null 等）。
默认组 ：json.Marshal(v)（纯 v2 默认）------ 记录 null→[] / {}、字段省略变化、是否新增 error。

契约测试建议覆盖：空切片 vs nil 切片、零值 bool/number、非法 UTF-8、故意重复的 object name（若有手写 jsontext / 原始输入路径）。前两条管客户端兼容；后两条管脏数据从静默变 error 后谁接。

对齐组绿、默认组 Diff 在文档预期内，再进 option-by-option；对齐组就红，先查是不是把 DefaultOptionsV1 写错包，或混进了未声明的自定义 Options。

5. 决策流：v1 → DefaultOptionsV1 → 逐项放开 → 纯 v2

读图顺序建议：

先问要不要迁------服务稳定、无新 Options 诉求，可停在 v1。
要迁就先锁行为 ------json.Marshal(v, jsonv1.DefaultOptionsV1())。
用表驱动对照 3--5 条行为差 ------尤其 nil 切片与 omitzero。
再 option-by-option 放开------每次只覆盖一个 Option，便于归因。
nojsonv2 是逃生舱，不是迁移动作本身------见下一节。

6. 渐进迁移与 jsonsplit（旁证）

官方迁移文给出三条路径（jsonv2-migration §Migration）：

all-at-once：直接接受 v2 默认（适合绿场或测试覆盖极强的模块）。
option-by-option ：DefaultOptionsV1 之后逐项覆盖------本稿主推。
差分旁证 ：github.com/go-json-experiment/jsonsplit 的 CallBothButReturnV1 一类 API，同时走 v1/v2 路径做对比。

jsonsplit 是官方迁移文档点名的实验仓库，旁证即可，别写成「不接第三方就迁不了」。生产主路径仍是 Options + 单测 / 契约测试；差分工具适合在核心 DTO 上抓回归。

7. `GOEXPERIMENT=nojsonv2`：构建期回退实现，不是「别用 v2」

go.dev/doc/go1.27 明文：若与新实现 不兼容，可在构建期 设置 GOEXPERIMENT=nojsonv2，恢复原始 v1 实现 。该 opt-out expected to be removed in a future release。

两件事别混：

说法	对不对
构建时打开 `nojsonv2`，让 v1 包回到旧实现	✅ 官方口径
设了 `nojsonv2` 就不能再 `import "encoding/json/v2"`	❌ 误读；文档关的是 v1 背后的实现切换
运行期 `export` 一下就永久生效、无需重建	❌ 文档写的是 build time
可以当长期生产默认依赖	❌ expected 未来移除；只作升级窗口逃生舱

和「迁到 v2 API + DefaultOptionsV1」分两段写进 runbook：前者是 API/行为迁移；后者是实现层兼容开关。别混成一步。

bash 复制代码

# 构建期示例（示意；按你们 CI 注入 GOEXPERIMENT）
GOEXPERIMENT=nojsonv2 go build -o app ./cmd/app

金丝雀只在「v1 包行为异常、且尚未完成 Options 对齐」时启用；API 已迁且单测绿，优先修 Options / 数据，别长期挂着 experiment 开关。

8. 升级窗口里怎么排进清单

建议写进发布检查：

版本钉死 ：go version 确认 1.27.x；GA 口径 2026-08-19；补丁可跟到核对时的 1.27.2（2026-10-08）。
默认组（可不迁） ：继续 encoding/json，跑核心序列化单测，确认无意外错误文案依赖（文案可能变）。
安全迁组 ：callsites → v2 API + jsonv1.DefaultOptionsV1()；对 nil slice/map、omitzero、非法 UTF-8、重复键四条做表驱动断言。
放开组：每次只去掉/覆盖一个 Option；Diff 进升级报告。
逃生舱 ：仅短期 GOEXPERIMENT=nojsonv2；标注 expected 移除，避免写进长期镜像基线。

一次只改一个变量：别把 json/v2 迁移和 Green Tea / 其它 runtime 实验捆同一轮 Diff，归因会糊。

对依赖方（网关、移动端、其它语言服务）提前同步两句：一是「在去掉 DefaultOptionsV1 前，切片仍可能是 JSON null」；二是「纯 v2 默认后非法 UTF-8 / 重复键会变 error，别假设静默成功」。比上线后再追客户端判空便宜。

9. FAQ

Q：Go 1.27 的 encoding/json/v2 必须立刻迁吗？

A：不必。官方写明 encoding/json 永续、可以不迁。新代码可用 v2；旧路径继续合法。

Q：怎么用 DefaultOptionsV1 保证迁完行为不变？

A：import jsonv1 "encoding/json" 与 "encoding/json/v2"，调用 json.Marshal(v, jsonv1.DefaultOptionsV1())（Unmarshal 同理）。该 Options 在 v1 包 ；官方说明其语义等价于旧 jsonv1.Marshal。

Q：omitempty 和 omitzero 在 v2 里差在哪？

A：v2 将 omitempty 重定义为「编码成空 JSON 值则省略」。bool / number / pointer / interface 上的旧 omitempty 用法应迁到 omitzero（v1/v2 均支持）。按类型改，勿整表盲换。

Q：升级后 nil 切片从 null 变成 \[\] 怎么办？

A：先确认是否已在纯 v2 默认下编码。需要对齐旧客户端时，用 DefaultOptionsV1 或显式 Options 保留 v1 行为；同时评估下游是否仍用 null 判空，必要时双边契约一起改。

Q：GOEXPERIMENT=nojsonv2 是不是意味着别用 v2 API？

A：不是。它是构建期恢复 旧 v1 实现 的兼容开关，expected 未来移除；与是否 import encoding/json/v2 不是同一句话。

10. 小结

Go 1.27（2026-08-19 GA）正式提供 encoding/json/v2，但 v1 不会消失 ------可以不迁。要迁时，安全顺序是：v2 API + encoding/json.DefaultOptionsV1 → 对照 nil 切片 / omitzero / UTF-8 / 重复键 → option-by-option 放开 → 再接受纯 v2 默认。GOEXPERIMENT=nojsonv2 只做构建期实现回退，且 expected 移除；不要误读成「禁止 v2 API」。jsonsplit 可作差分旁证，不是迁移动作的前置依赖。先把「可不迁 / 先锁行为」写进升级清单，比全仓改 import 再撞行为差省事。

Go1.27升级后json/v2怎么安全迁