Go 1.27 encoding/json/v2新 JSON 包适合哪些迁移边界

Go 1.27 的 encoding/json/v2 适合“有测试、有明确 JSON 契约、愿意逐项处理输入边界”的项目，不适合把一个没有回归样本的老接口直接整体替换。我的判断顺序通常是先区分 API 是否能编译，再确认 JSON 行为是否允许变化，最后才决定要不要打开 v2 的严格默认值。

官方资料：https://go.dev/doc/jsonv2-migration

迁移不是非黑即白：旧的 encoding/json 会继续保留，第一步可以把调用切到 encoding/json/v2 并使用 jsonv1.DefaultOptionsV1()，先保住既有语义，再逐项接受更严格的行为。

先看清真正会出问题的四个边界

Go 1.27 的 v2 API 在简单 Marshal、Unmarshal 调用上很接近旧包，所以编译通过并不代表迁移安全。官方迁移指南特别提醒，v2 默认拒绝 JSON 字符串中的无效 UTF-8，也拒绝对象中的重复名称；另外 nil 切片和 nil map 的默认输出，以及结构化 tag 的错误处理，也可能改变接口结果。

这四项的共同点是：它们可能让原来“悄悄接受”的数据变成错误，或让原来序列化出的 null 变成空数组、空对象。对内部数据结构影响较小，但对签名、缓存键、第三方回调和持久化快照影响很大。

第一步用 v1 兼容选项切换 API

如果项目已经有大量旧调用，建议先把迁移拆成两次提交。第一次只改变 import 和调用入口，使用 v1 兼容选项；这样可以尽早获得新包的 API 形态，同时不让所有 JSON 行为在同一次发布里改变。

package main

import (
    "fmt"
    jsonv1 "encoding/json"
    jsonv2 "encoding/json/v2"
)

type Profile struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

func main() {
    value := Profile{ID: "u-1001", Name: "Go"}

    // 先采用 v1 兼容语义，降低第一次替换 import 的行为风险。
    data, err := jsonv2.Marshal(value, jsonv1.DefaultOptionsV1())
    if err != nil {
        // 编码失败必须向调用方返回错误，不能用空 JSON 静默替代。
        panic(err)
    }
    fmt.Println(string(data))
}

DefaultOptionsV1 是迁移缓冲层，不是永久的“关闭 v2”开关。等调用点完成切换后，可以把它拆成更小的兼容选项，并为每一项补充输入样本、黄金 JSON 或协议测试。

再逐项打开严格语义，不要一次改完

第二阶段要按业务边界逐项删除兼容项。先处理内部消息和新接口，再处理已经被外部系统依赖的公共协议。比如重复键在旧代码中可能被后值覆盖，但 v2 默认会把它当作错误；如果你确实要兼容一段历史输入，应把兼容范围写在边界适配器里，不要把整个服务都放宽。

package main

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

type Event struct {
    Labels []string `json:"labels"`
}

func decodeEvent(input []byte) error {
    var event Event

    // 这里不再传入 DefaultOptionsV1，让 v2 对输入采用更严格的默认判断。
    if err := jsonv2.Unmarshal(input, &event); err != nil {
        // 生产代码应记录协议来源和请求编号，但不要把敏感原文写入日志。
        return fmt.Errorf("decode event: %w", err)
    }
    fmt.Printf("labels=%v\n", event.Labels)
    return nil
}

测试要覆盖“合法输入”和“旧系统曾经接受但新语义拒绝的输入”两组样本。尤其要关注无效 UTF-8、重复对象名、nil slice/map，以及自定义 marshal/unmarshal 方法的行为；这些是迁移后最容易从日志和接口对比中暴露的差异。

哪些项目适合现在迁移，哪些应该先等等

适合现在开始的通常是内部服务、新接口、能控制上下游的消息流，以及已经有 JSON 回归测试的代码库。它们可以先使用兼容选项完成 API 替换，再把严格语义作为小范围配置打开，出问题时也容易按接口回滚。

应该谨慎的包括对外公开协议、依赖旧版重复键或 null 形态的客户端、把 JSON 文本直接用于签名或缓存键的系统，以及没有历史样本的遗留服务。这里不是说永远不能迁移，而是要先建立一份“旧输入、旧输出、新预期”的对照表。

迁移时我会保留的检查清单

• 先确认代码使用的是 Go 1.27 或更高版本，再把 encoding/json/v2 纳入单独变更。
• 为无效 UTF-8、重复键、nil slice/map 和 tag 边界准备固定样本。
• 先用 jsonv1.DefaultOptionsV1() 保持兼容，再一次只打开一类 v2 语义。
• 对公共协议、签名、缓存和持久化数据做旧新结果对照，而不只看单元测试是否通过。

一句话总结：encoding/json/v2 的价值不只是换一个包名，而是把过去容易被忽略的 JSON 边界显式化。新项目可以从严格默认开始；老项目更适合先兼容、再分项收紧，迁移边界应由协议控制权和回滚能力决定。

相关问题

旧的 encoding/json 还能继续用吗？
可以。Go 官方迁移指南明确说明旧包不会消失，已有代码不要求立即迁移。

只把 import 改成 encoding/json/v2 就够了吗？
只对简单调用来说可能能编译，但仍要检查无效 UTF-8、重复键、nil 值和 tag 语义，不能把编译通过当作协议兼容证明。

能不能一次把所有 DefaultOptionsV1 都删掉？
除非项目已经有足够的历史样本和回归对照，否则不建议。按边界逐项打开更容易定位差异，也保留了清晰的回滚点。