Go 1.27 的 encoding/json/v2 迁移指南解决哪些兼容问题

Go 1.27 把 encoding/json/v2 从实验能力带进标准库。它的 API 仍然熟悉，但默认语义更严格：非法 UTF-8 和对象重复名称会报错，nil 切片与 nil map 默认分别编码为空数组和空对象。真正需要评估的不是“能不能编译”，而是下游服务是否依赖旧 JSON 文本。

小项目可以直接替换 import 并跑契约测试；有外部消费者的服务，先用 DefaultOptionsV1 或 jsonsplit 保持旧输出，再逐项启用 v2 行为。

Go 1.27 的 JSON 迁移到底改变了什么

Go 1.27 新增 encoding/json/v2，同时提供更底层的 encoding/json/jsontext。前者负责 Go 值与 JSON 值的语义映射，后者处理 Token、Value 和流式 JSON 文本。原来的 encoding/json 继续遵守 Go 1 兼容承诺，且在 Go 1.27 中由 v2 实现支撑，但保留 v1 的行为。

因此，迁移指南首先解决的是“哪些地方会悄悄改变”。如果接口只供本服务内部使用，空数组通常比 null 更容易统一处理；如果 JSON 已经被前端、合作方或消息消费者固化，就必须把输出差异当作兼容性变更。

简单项目如何完成一次最小迁移

没有长期外部契约的命令行工具或内部服务，可以先把 import 改为 v2，再运行单元测试、JSON 快照和几组边界样本。最小写法仍然接近旧 API：

package main

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

type Response struct {
    Items []string `json:"items"`
}

func main() {
    // 用 nil 切片验证 v2 的默认输出是否符合接口约定。
    data, err := json.Marshal(Response{})
    if err != nil {
        // 生产代码应把编码错误交给调用方，而不是静默返回空响应。
        panic(err)
    }
    fmt.Println(string(data))
}

这里的关键检查不是程序能否打印 JSON，而是消费者是否接受 {"items":[]}。还应增加重复对象名、非法 UTF-8 和无效标签样本，确认错误被记录、返回或转成合适的 HTTP 状态。Go 1.27.1 已包含 encoding/json 相关修复，升级到当前 1.27.x 后再做回归更稳妥。

有兼容压力时怎样逐项打开 v2 行为

复杂项目不要一次性接受全部默认值。迁移第一阶段可以显式使用 v2 API，但传入 v1 兼容选项：

package main

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

type Payload struct {
    Items []string `json:"items"`
}

func main() {
    // 先保留 v1 的 null 语义，降低切换 API 的瞬时风险。
    data, err := json.Marshal(Payload{}, jsonv1.DefaultOptionsV1())
    if err != nil {
        // 让调用方看到错误，便于把差异和输入样本关联起来。
        panic(err)
    }
    fmt.Println(string(data))
}

确认调用链稳定后，再一次只撤掉一个兼容行为。例如保留其他 v1 规则、只让 nil 切片使用 v2 的空数组，可以追加 json.FormatNilSliceAsNull(false)。每次修改都比较真实响应或快照，不要只测一个结构体；同一个选项在嵌套对象、指针字段和自定义 marshaler 上可能暴露不同影响。

如果实验阶段使用过旧的 inline 标签或 unknown 等选项，也要对照 Go 1.27 发布说明重看：部分实验选项已移除，inline 改名为 embed。这类问题应修正类型定义和标签，不建议靠屏蔽错误来掩盖。

生产服务怎样观测差异并切到纯 v2

在线服务更适合分层切换。github.com/go-json-experiment/jsonsplit 可以同时用 v1 和 v2 编解码，在 CallBothButReturnV1 模式下继续返回 v1 结果，同时报告两者差异；还可以用 AutoDetectOptions 缩小造成差异的选项范围。代价是一次请求可能多做一轮甚至多轮编解码，因此要把额外 CPU 和延迟纳入观察。

实际落地可以保留三类记录：输入样本的摘要、v1/v2 输出是否不同、差异对应的字段或选项。差异停止增长后，先切到只调用 v2 但继续保留对比，再删除过渡代码。若刚升级就遇到无法及时修复的兼容问题，GOEXPERIMENT=nojsonv2 可作为 Go 1.27 的临时回退开关，但它不是长期迁移方案，构建配置里应记录原因和撤销条件。

常见问题

旧项目必须改成 encoding/json/v2 吗？

不必须。旧 encoding/json 会继续维护并保留兼容语义；只有需要更严格默认值、新 API 或更清晰的编解码边界时，才值得安排迁移。

为什么只改 import 就出现 null 变成 []？

因为 v2 默认把 nil Go 切片编码为空 JSON 数组，把 nil map 编码为空对象。若旧接口必须保留 null，可先使用 DefaultOptionsV1()，再按字段或选项逐步改变。

jsontext 和 json/v2 应该一起迁移吗？

不一定。普通结构体编解码先迁移 encoding/json/v2 即可；只有需要 Token、Value 或更底层流式语法控制时，才引入 encoding/json/jsontext。

官方入口：encoding/json/v2 Migration Guide、Go 1.27 Release Notes。