Go工具链JSON实验开关对编码兼容性的影响范围

Go 1.27 的 JSON 变化不能只看成“多了一个 v2 包”。真正需要评估的是：原有 encoding/json 代码仍可继续使用，但它的底层实现已经切换到 v2；同时，v2 对无效 UTF-8、重复对象名、nil 切片和字段匹配采用了更严格或不同的默认语义。升级前先跑兼容矩阵，通常比上线后追查一条变成错误的输入更省时间。

官方地址：https://go.dev/doc/go1.27

Go 1.27 的 JSON 开关到底改变了什么

Go 1.25 时，GOEXPERIMENT=jsonv2 是试验入口；到了 Go 1.27，encoding/json/v2 和 encoding/json/jsontext 已作为标准库新包提供，原有 encoding/json 由 v2 实现支撑。也就是说，继续调用 json.Marshal 并不等于完全停留在旧实现上。

v1 API 仍然保留，业务不需要一次性改成 v2；但 v2 默认更关注互操作和输入明确性，例如拒绝无效 UTF-8、拒绝重复对象名，nil 切片和 map 的编码结果也可能与旧行为不同。错误文本变化也不能作为稳定契约保存。

先用四类输入做兼容性分层

不要只拿一组正常 JSON 跑通就宣布兼容。建议把真实接口样本和历史异常样本分成四类：正常对象、重复成员名、无效 UTF-8、nil 容器与大小写边界。下面的代码只展示测试组织方式，输出应由项目自己的 Go 版本和样本生成。

package compat

import (
    "encoding/json"
    "testing"
)

// 用同一组样本覆盖正常输入与边界输入，避免只验证 happy path。
func TestJSONCompatibility(t *testing.T) {
    cases := []struct {
        name string
        data []byte
    }{
        {"normal", []byte(`{"id":7,"name":"go"}`)},
        {"duplicate-name", []byte(`{"id":7,"id":8}`)},
        {"invalid-utf8", []byte{'{', '"', 'x', '"', ':', '"', 0xff, '"', '}'}},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            var dst map[string]any
            // 记录成功或错误即可，具体期望值由兼容策略决定。
            if err := json.Unmarshal(tc.data, &dst); err != nil {
                t.Logf("sample=%s rejected: %v", tc.name, err)
            }
        })
    }
}

这段测试的重点不是断言所有输入都成功，而是把“旧实现能接受、新实现拒绝”的差异固定下来。对外 API 应该把解析错误映射成稳定的业务错误，不要直接依赖错误字符串。

三种构建方式怎样放进 CI

迁移时至少保留两条流水线：一条使用 Go 1.27 默认行为，另一条在同一提交上使用 GOEXPERIMENT=nojsonv2 做对照。若项目显式导入 encoding/json/v2 或 encoding/json/jsontext，还要把这部分包单独列出，因为旧实现回退并不能覆盖新 API 的依赖。

# 默认实现：检查升级后的真实行为
go test ./...

# 临时对照：定位是否由 jsonv2 底层实现触发差异
GOEXPERIMENT=nojsonv2 go test ./...

# 使用新 API 的包要单独编译；不把回退开关当成长期方案
go test ./internal/jsonv2/...  # 这里的目录替换为项目实际包路径

CI 结果建议按“解析错误、编码差异、性能变化、显式 v2 编译失败”分类，而不是只统计一项总失败数。默认测试通过、回退测试通过，并不代表数据契约没有变化；还要比对响应快照和错误处理分支。

迁移与回退的边界要先写清

普通业务可以继续使用 encoding/json，先解决数据边界，再逐步引入 v2 的选项或新接口。需要流式读写、严格 JSON 互操作或希望显式控制语义时，再评估 encoding/json/v2 与 jsontext。自定义序列化类型尤其要重跑指针接收者、嵌入字段和标签相关测试。

GOEXPERIMENT=nojsonv2 的价值是定位问题和争取修复窗口，不是把生产环境永久锁在旧实现上。若回退后问题消失，应保留最小复现、升级前后输入和依赖版本，向 Go 项目或依赖维护者反馈，再回到默认实现验证修复。

• 没有失败样本：先补齐重复字段、编码和 nil 容器样本。
• 只有错误文本变化：改用错误类型、错误分类或业务码判断。
• 显式 v2 包编译失败：检查 Go 版本和依赖约束，不要只切换回退开关。
• 接口快照变化：确认是语义变化还是测试依赖了不稳定的字段顺序或错误文本。

相关问题

升级 Go 1.27 后必须立刻改成 encoding/json/v2 吗？

不必须。旧的 encoding/json 会继续存在，适合先通过测试评估影响；是否显式迁移取决于对严格默认值、流式 API 和新选项的需求。

为什么同样调用 json.Unmarshal，升级后却多了错误？

底层实现和默认语义发生了变化，异常 UTF-8、重复字段或结构标签边界可能从“接受”变成“拒绝”。应优先定位输入类别，不要先改成忽略错误。

nojsonv2 能不能作为长期兼容配置？

不建议。它是暂时恢复旧实现的构建时回退，应配套最小复现和跟踪项；长期方案仍是修复数据、代码或依赖的兼容问题。