Go 1.27 encoding/json/v2 怎么试用：旧 API 边界、选项配置与回归核对

把服务从 Go 1.26 编译器换到 Go 1.27 后，最容易被忽略的不是业务代码能不能编译，而是 JSON 边界有没有悄悄变严。encoding/json 仍然保持原有 API，底层实现已经切到 v2；如果项目只接受规范 JSON，通常可以先观察回归结果，再决定是否直接使用 encoding/json/v2 的新 API。

先划清 Go 1.27 的迁移范围

Go 1.27 同时提供 encoding/json/v2 和更底层的 encoding/json/jsontext。前者负责结构体与 JSON 值之间的常规转换，后者面向 Token、Value 和流式语法处理。普通 HTTP 接口、配置文件和消息体，先从 v2 的高层 API 评估就够了；只有需要逐 Token 检查 JSON 文本时，才进入 jsontext。

这里有一个重要的缓冲区：原来的 encoding/json 包仍然保留，Go 官方也明确表示不要求用户立刻迁移。升级动作应该拆成“先验证旧调用点，再为新边界建立小范围试用”，不要把整个仓库改成一次性的版本赌注。

v1 与 v2 的差异集中在默认行为

先用最小样本验证 v2 的拒绝边界

不要一上来拿生产订单大报文试验。准备两个几十字节的输入：一个让同名字段出现两次，另一个把字符串中的字节故意置为非法 UTF-8。测试的重点不是比较错误文案，而是确认“成功还是拒绝”符合新实现的预期。

package jsonv2_test

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

func TestStrictJSONBoundaries(t *testing.T) {
    var got map[string]any

    if err := jsonv2.Unmarshal([]byte(`{"id":1,"id":2}`), &got); err == nil {
        t.Fatal("duplicate object names should be rejected")
    }

    invalidUTF8 := []byte{'{', '"', 'n', '"', ':', '"', 0xff, '"', '}'}
    if err := jsonv2.Unmarshal(invalidUTF8, &got); err == nil {
        t.Fatal("invalid UTF-8 should be rejected")
    }
}

这段测试只锁定语义，不锁定完整错误字符串。Go 1.27 的发布说明特别提醒，encoding/json 继续兼容原行为，但错误消息的精确文本可能变化；如果业务把错误字符串直接当协议字段，应该先改成错误类型或自己的稳定码。

需要兼容旧数据时，把选项放在边界层

v2 的高层函数接受可变数量的 Options，因此兼容设置应该集中在消息入口或适配层，而不是散落在每个业务函数里。先让一个消费者、一个回放任务或一条内部队列使用 v2，再比较成功率、拒绝原因和下游字段变化。

如果旧数据依赖 v1 的宽松行为，优先使用官方提供的 v1 语义选项完成过渡，并在代码旁写清删除条件。不要为了让测试变绿而全局关闭校验：那样只会把数据质量问题推迟到另一个服务。

回归检查要覆盖业务字段，而不只是编译成功

我更建议把检查分成四组：普通对象的字段结果、重复名称、非法 UTF-8，以及自定义类型和 struct tag。每组都保留原始输入、期望的成功/失败结论和关键业务字段；错误文本只做辅助断言。

• 普通对象：比较必填字段、零值字段和时间格式，不只比较整段 JSON 字符串。
• 重复名称：确认入口拒绝后，HTTP 层返回自己的 4xx 结构，不把内部错误直接暴露给客户端。
• 非法 UTF-8：确认日志、指标和死信记录不会再次按字符串编码失败。
• struct tag：检查嵌入字段、string 等标签语义，尤其是历史数据的反序列化结果。

出现问题时怎样回退而不制造新版本

Go 1.27 提供 GOEXPERIMENT=nojsonv2，构建时设置它可以恢复旧的 encoding/json 实现。这个开关适合止损，不适合长期藏在正式构建脚本里。回退时要同时记录触发样本、受影响服务、构建参数和下一次复测时间，否则团队很快会忘记为什么保留它。

GOEXPERIMENT=nojsonv2 go test ./...
GOEXPERIMENT=nojsonv2 go build ./cmd/api

如果只有一个消费者失败，先缩小到该消费者的输入集合；如果多个服务都在同一类样本上失败，再回到共享适配层处理。回退成功并不等于迁移完成，它只证明旧实现仍能承接当前流量。

给 Go 1.27 JSON 迁移留一张清单

1. 在 go.mod 更新后先跑原有测试，记录错误数量和错误类型变化。
2. 为重复字段和非法 UTF-8 增加最小回归样本，确认 v2 的默认拒绝符合接口契约。
3. 挑选一个低风险入口试用 encoding/json/v2，观察业务字段而非只看编译结果。
4. 把兼容选项集中在适配层，避免业务层到处携带迁移开关。
5. 若必须回退，保存 GOEXPERIMENT=nojsonv2 的构建记录，并为移除它设定验收条件。

常见问题

Go 1.27 是否必须把 encoding/json 改成 encoding/json/v2？

不必须。旧包继续支持，先用现有测试确认升级影响，再选择单个入口试用 v2 更稳。

为什么重复 JSON 字段现在会让测试失败？

v2 默认采用更严格、互操作性更好的规则，重复对象名称属于需要调用方明确处理的输入，而不是静默覆盖。

可以一直设置 GOEXPERIMENT=nojsonv2 吗？

不建议。它是临时回退手段，应该和触发样本、负责人、复测条件一起记录，避免把兼容问题永久隐藏。

encoding/json/jsontext 什么时候值得使用？

当程序需要按 Token 或 Value 处理 JSON 语法、做流式检查或保留更底层的文本控制时再使用；普通结构体编解码优先考虑高层 API。

总结

Go 1.27 的 JSON 变化更适合分阶段吸收：旧 API 先保持运行，v2 用小样本验证严格边界，兼容选项集中管理，回退开关只用于止损。真正要验收的是业务字段和输入契约，而不是一份恰好通过编译的构建日志。