Go 1.27 新 JSON API 适合先迁移哪类编码场景

如果你正在评估Go 1.27版本新推出的JSON API，完全不用上来就全量替换现有项目的所有JSON逻辑，优先选改造成本低、没有特殊定制规则的场景试水就好。

优先迁移无需自定义序列化/反序列化扩展逻辑、仅依赖标准基础类型完成JSON编解码的场景，比如常规后端HTTP接口的响应输出、项目本地结构化配置文件的读写操作，这类场景适配几乎不用改动原有业务逻辑，就能直接用上新API的性能优化特性。

我第一次看到 Go 1.27 的 JSON 更新时，直觉是把所有 encoding/json 的 import 都换成 encoding/json/v2。真正把迁移边界列出来后，我反而觉得这不是一项适合“全库替换”的改动：API 层面很顺，数据契约层面却可能改变客户端看到的结果。

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

迁移说明：https://go.dev/doc/jsonv2-migration

如果只问“先迁移哪类场景”，我的答案是：新项目或新接口、团队能控制输入质量的边界、以及已有契约测试的内部数据流。对外接口如果依赖 null、大小写容错或重复键处理，则应先做对照测试，再决定是否切换。

我先把 Go 1.27 的 JSON 变化拆开看

这次不是单纯增加一个替代包。Go 1.27 提供了高层的 encoding/json/v2，同时提供更底层的 encoding/json/jsontext；原来的 encoding/json 仍然存在，并由新的实现支撑，官方也明确表示不要求现有程序立刻迁移。

对我来说，最有价值的变化有两层。第一层是 API：例如把 JSON 直接写入 io.Writer 可以使用 MarshalWrite，不必先围绕旧的 Encoder 组织代码。第二层是默认行为：v2 对非法 UTF-8 和对象重复名称更严格，nil slice 和 nil map 默认也不再编码成 JSON null。

所以“能不能编译”不是迁移完成的标志。只改 import，代码可能马上通过编译；真正需要确认的是下游服务、前端和缓存中的 JSON 形状有没有被当成协议使用。

最适合先迁移的是这三类场景

我会把第一批目标限定在三类边界。第一类是新项目和新接口，尚未被旧客户端绑定输出细节，可以从一开始接受 v2 的更严格默认值。第二类是输入校验边界，例如导入服务、消息消费或配置接收层，拒绝非法 UTF-8 和重复对象名通常比默默修正更容易排查问题。第三类是内部数据流，生产者和消费者由同一团队维护，并且可以用契约测试锁住输出。

一个很小的入口就能体现 API 变化。下面的代码只演示写入器调用，不代表已经替团队验证过所有业务字段；正式切换时仍要把旧输出和新输出放进契约测试。

package main

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

type Event struct {
    Name string `json:"name"`
}

func main() {
    var buf bytes.Buffer
    // 直接把结构写入 io.Writer，适合新接口或内部边界。
    if err := json.MarshalWrite(&buf, Event{Name: "created"}); err != nil {
        // 保留错误，让调用方决定重试、记录或返回接口错误。
        panic(err)
    }
    fmt.Println(buf.String())
}

存量接口先别急着整库替换

迁移说明里最值得留意的是“API 差异小，行为差异大”。例如同一个 nil slice，v1 默认输出 null，v2 默认输出空数组 []。对新接口这可能是更清楚的表达；但如果前端把 null 当成“没有加载”，把 [] 当成“已加载但为空”，同一处改动就会变成可见的协议变化。

类似风险还有三类：v2 默认拒绝非法 UTF-8，默认拒绝 JSON 对象中的重复名称；结构体字段匹配也更偏向大小写敏感。历史系统如果依靠这些宽松行为接收外部数据，先改包名可能把隐藏的兼容逻辑直接变成错误。

这也是我不会把“更严格”简单等同于“对所有服务都更好”的原因。严格默认值适合把问题尽早暴露出来，但存量接口要先回答：消费者是否依赖旧输出？历史数据是否包含非 UTF-8 字节？重复字段是否曾被某个客户端容忍？

我会用一轮契约测试决定下一步

我的做法是先挑一个边界最清楚的 package，保存一组真实代表性的 JSON 输入和输出，再分别用旧 API 与 v2 处理。重点不是比较字符串是否完全相同，而是把差异分类：可以接受的格式变化、必须保持的兼容字段、以及应该升级为错误的脏数据。

如果业务必须暂时保留 v1 语义，可以在 v2 API 上使用对应选项，例如迁移指南给出的 DefaultOptionsV1，先把包名和调用方式迁过去，再逐项打开 v2 行为。这样比一开始同时改变所有默认值更容易定位回归。

# 先运行边界测试，再扩大迁移范围。
go test ./...
# 只把已确认的 package 纳入本轮切换，不要一次替换整个仓库。

最后再看是否需要 jsontext。大多数普通结构体编码不必直接接触底层 Token 和 Value；只有需要更细粒度控制 JSON 文本、流式处理或语法层边界时，才值得把它作为单独的迁移主题。

相关问题

Go 1.27 会删除原来的 encoding/json 吗？

不会。官方迁移指南说明原包受 Go 兼容性承诺保护，现有程序没有被要求立刻迁移。是否切换，应该由接口契约和测试覆盖决定。

用了 encoding/json/v2 就必须同时使用 jsontext 吗？

不需要。v2 负责常见的高层编码与解码；jsontext 更适合需要观察或控制 JSON 语法层的场景，两者可以按边界分别采用。

我的结论是：Go 1.27 的 JSON 更新值得尽早试，但第一批目标应是“契约由我控制”的边界。先迁移新接口和严格输入，再处理有真实测试保护的内部流；对外存量接口，先把 null、空数组、重复键和 UTF-8 行为写进测试，迁移就会从一次冒险的全库替换变成可回滚的分段决策。