Go 1.27 的 encoding/json/v2 变严格了吗：重复字段、非法 UTF-8 与迁移验收

Go 1.27 发布后，很多团队会先看到一个看似矛盾的结果：项目仍然能编译，正常 JSON 请求也能通过，但以前被默默接受的重复字段、非法 UTF-8 或错误信息，在升级后的测试里开始暴露。原因不是 encoding/json 突然要求所有项目立刻改成新 API，而是它已经由 v2 实现支撑，默认行为和错误边界更值得重新验收。

升级后为什么“能跑”却不代表行为完全没变

Go 官方对 Go 1.27 的表述很克制：现有 encoding/json API 继续支持，编解码结果尽量保持兼容，但底层实现切换后，精确的错误文本可能不同，v2 也提供了更严格的默认语义。换句话说，业务主链路可能没有任何编译错误，测试夹具、日志断言和边界输入却可能先报警。

这里先别急着把所有调用改成新包。第一步是找出项目真正依赖的行为：是把重复字段当成合法输入，还是只关心最终结构体值；是把错误字符串写进监控规则，还是只判断 err != nil。这两个答案会直接改变迁移成本。

先用三个输入复现团队最容易漏掉的边界

可以在临时测试文件里保留下面的输入样本。示例故意不绑定业务字段，便于放进网关、配置中心或消息消费服务的回归测试。

var payloads = [][]byte{
    []byte(`{"id":1,"id":2}`),
    []byte("{\"name\":\"" + string([]byte{0xff}) + "\"}"),
    []byte(`{"id":1,"name":"ok"}`),
}

for _, payload := range payloads {
    var dst map[string]any
    err := json.Unmarshal(payload, &dst)
    t.Logf("payload=%x value=%v err=%v", payload, dst, err)
}

第三个样本代表正常路径，第一、第二个样本才是迁移验收的重点。对每个输入至少记录三项：是否返回错误、目标值最后保留什么、错误是否被业务代码按字符串匹配。不要把终端输出原样复制进接口文档，先确认它确实是你当前 Go 版本和当前调用路径产生的结果。

重复字段与非法 UTF-8 分别说明了什么

重复字段往往来自客户端拼接参数、代理重试合并或手写 JSON。旧代码如果只取最后一个值，可能一直没有暴露问题；更严格的 JSON 语义会把它变成可观察的输入质量问题。非法 UTF-8 则更像数据源或转码链路故障，继续“尽量解析”可能掩盖上游损坏。

如果同一份输入在 encoding/json 和 encoding/json/v2 上得到不同结果，把差异固定成测试用例比在生产日志里猜测更有效。对于签名、审计或幂等键相关的 JSON，尤其要保留原始字节和解析后的结构两份证据。

迁移时如何在兼容与严格校验之间做选择

Go 1.27 的 v2 包适合新代码或愿意明确配置 JSON 语义的边界服务。已有项目可以先维持原入口，再按模块逐步引入迁移指南中的选项。这个过程建议拆成两次发布：第一次只增加观测和回归样例，第二次才改变线上拒绝策略。

// 新代码按模块引入 v2，具体选项以当前版本文档为准。
import jsonv2 "encoding/json/v2"

func decodeOrder(data []byte) (Order, error) {
    var order Order
    err := jsonv2.Unmarshal(data, &order)
    return order, err
}

如果升级后必须快速确认是不是新 JSON 实现导致回归，可以在隔离的构建任务里临时使用 GOEXPERIMENT=nojsonv2 做对照。它是定位手段，不应该被当作长期迁移方案；对照结果要和输入样本、Go 版本、构建参数一起记录。

一份能落到 CI 的 Go 1.27 验收清单

1. 固定 go version、操作系统和构建参数，避免把环境差异误判成 JSON 差异。
2. 加入正常对象、重复字段、非法 UTF-8、未知字段和超长数字等输入样本。
3. 断言结构化结果和错误类型/状态，不要只断言完整错误字符串。
4. 检查网关、消息消费者、签名校验和日志脱敏是否各自有一条 JSON 路径。
5. 灰度期间统计解析失败原因；确认没有异常增长后，再移除临时兼容开关。

最终验收应回答一个很具体的问题：这次升级是否改变了业务允许的输入集合？如果答案是“没有”，就把测试补齐并继续升级；如果答案是“有”，先让产品和接口负责人确认新边界，再发布拒绝策略。

相关问题

Go 1.27 必须立刻把所有代码改成 encoding/json/v2 吗？

不需要。官方仍支持原有 encoding/json API，先做边界输入回归，再按服务风险拆分迁移更稳妥。

为什么不建议用错误字符串做长期兼容判断？

错误文本可能随实现变化。接口层应转换成稳定的错误码或状态，日志里再保留原始错误供排查。

非法 UTF-8 应该自动替换后继续处理吗？

只有在业务明确允许丢失字符时才考虑替换。订单、签名、审计等链路更适合拒绝并追查上游编码。

把新闻里的版本变化变成一次可回滚的工程变更

Go 1.27 的重点不是要求所有项目同一天换 API，而是让 JSON 输入边界更值得被明确记录。把三类异常样本放进 CI，停止依赖错误文本，给构建参数和灰度结果留痕，再决定是否启用更严格的 v2 语义，升级就从“跟着版本号走”变成了可验收的工程动作。