Go 1.27 encoding/json/v2 正式进入标准库

Go 1.27 的 JSON 变化不是把旧包突然删除，而是把一套更严格、可配置的 JSON 语义正式带进标准库：新增 encoding/json/v2 和 encoding/json/jsontext，原有 encoding/json 继续可用，并由 v2 实现提供底层支持。新项目可以直接采用 v2，存量服务则应先围绕协议边界做灰度，而不是看到新包就全量替换。

真正需要关注的结果是默认行为变严：v2 默认拒绝重复成员名和非法 UTF-8，结构体字段匹配也更偏向大小写严格。Go 1.27 仍承诺 v1 API 兼容，迁移重点因此落在输入数据和跨服务约定，而不是 import 路径本身。

Go 1.27 的三个 JSON 层次如何分工

encoding/json/v2 是日常使用的高层 API，提供 Marshal、Unmarshal、MarshalWrite、UnmarshalRead 等函数，并允许通过可变参数 Options 调整语义。encoding/json/jsontext 则把 JSON 当成 Token 和 Value 序列处理，适合需要保留语法边界、流式读取或做更细粒度协议工具的场景。

对存量代码而言，encoding/json 的包名和 v1 调用方式仍然存在。发布说明还特别说明，旧包由 v2 实现支撑，但行为会保持兼容，只有错误文本可能变化。换句话说，标准库内部完成了演进，应用层可以按服务、接口或数据源逐步选择新语义。

严格默认值会改变哪些输入结果

v2 的收紧主要服务于互操作性和安全边界。JSON 对象出现同名成员时，不同语言可能采用第一个值、最后一个值或合并值；v2 默认拒绝这类输入，避免认证服务和业务服务对同一请求产生不同解释。字符串中出现非法 UTF-8 时，v1 会替换为 Unicode replacement character，v2 默认报错，避免数据被悄悄改写。

结构体字段匹配也值得单独回放。v1 默认较宽松地做大小写匹配，v2 默认大小写严格；需要兼容 camelCase、snake_case 或旧客户端时，可以在字段标签中明确写出策略，或使用 MatchCaseInsensitiveNames。unknown member 默认仍会被忽略，若接口希望拒绝拼写错误或未授权字段，再显式使用 RejectUnknownMembers。

新代码和存量服务的迁移方式

新代码可以从一个明确的边界函数开始使用 v2，把选项集中放在适配层，避免业务代码到处传配置。下面的例子保留严格默认值，只对字段名和错误做最小处理：

package main

import (
    "fmt"
    "log"

    "encoding/json/v2"
)

func main() {
    type Event struct {
        EventID string `json:"eventId"`
        Count   int    `json:"count,omitzero"`
    }

    // 统一在边界处解码，重复键和非法 UTF-8 会返回错误。
    input := []byte(`{"eventId":"build-127","count":2}`)
    var event Event
    if err := json.Unmarshal(input, &event); err != nil {
        // 生产代码应记录接口名和请求追踪号，不要原样打印敏感载荷。
        log.Printf("JSON decode failed: %v", err)
        return
    }

    // omitzero 只影响零值字段，输出仍由 v2 的严格语义控制。
    output, err := json.Marshal(event)
    if err != nil {
        log.Printf("JSON encode failed: %v", err)
        return
    }
    fmt.Println(string(output))
}

存量服务先不改 import，重点是用 Go 1.27 重新跑协议样本：正常 payload、重复键、错误编码、不同字段大小写，以及携带未知字段的请求。若只是旧实现带来的兼容性回归，发布说明提供了 GOEXPERIMENT=nojsonv2 构建期开关作为临时回退；它是过渡手段，不应代替对上游数据的修复。

上线前的 JSON v2 检查清单

把检查放在协议边界，不要只测一条成功样本。至少保留一组重复成员名和非法 UTF-8 的失败断言，确认错误能被网关或服务正确归类；为大小写字段写一条兼容测试，防止客户端命名风格变化被误判为缺字段；对未知成员明确“忽略还是拒绝”的接口约定。跨版本项目还要分别执行 Go 1.26 和 Go 1.27 的构建、单元测试与接口回放，避免把工具链差异误认为业务变化。

如果服务既要接受历史客户端，又要逐步启用严格语义，可以按接口拆分适配层：先记录异常样本，再对低风险读接口启用 v2，最后处理写接口和认证链路。这样既能利用更快的反序列化实现，也能把不可预期的兼容性风险限制在可观测范围内。

常见问题

Go 1.27 发布后必须把 encoding/json 改成 encoding/json/v2 吗？

不必须。v1 API 仍受支持，优先迁移有明确协议收益或性能收益的边界即可。

重复 JSON 键以前能解析，升级后为什么失败？

v2 默认拒绝重复成员名，因为不同服务可能对重复键采用不同覆盖规则。先清理上游生成逻辑，再决定是否显式允许兼容输入。

encoding/json/jsontext 适合普通业务接口吗？

普通接口通常使用 encoding/json/v2 就够了；只有需要 Token、Value、流式语法或自定义协议处理时，才下沉到 jsontext。

Go 1.27 的官方发布说明：https://go.dev/doc/go1.27；API 细节可查看：https://pkg.go.dev/encoding/json/v2。版本升级后先回放真实协议样本，再决定迁移范围，通常比一次性替换包名更稳。