Go 项目里 JSON 太常见了：HTTP API、配置、消息队列、日志、第三方回调，哪儿都有它。也正因为太常见，encoding/json 的历史包袱、性能、字段匹配、重复 key、流式处理这些问题，很多团队都踩过。Go 1.25 引入实验性的 JSON v2 和 jsontext，不是让你今天就全量替换，而是给我们一个重新审视 JSON 边界的机会。
这篇我会按生产迁移视角讲：JSON v2 想解决什么问题，哪些行为变化会影响老代码，性能优化该怎么验证，以及什么时候该继续留在 v1。
先别急着换库，先问是不是 JSON 真的慢
我见过不少团队一听到 JSON 性能问题，就准备上第三方库或者代码生成。结果压测一看，真正慢的是数据库、下游 HTTP、锁等待，JSON 只占 3%。这种情况下换 JSON 库，收益不大，风险倒是不小。
正确姿势还是老三样：profile 看 CPU 和分配，benchmark 看热点路径，线上指标看 P95/P99。只有当 JSON 编解码确实在热点路径上，才值得认真评估 v2 或其他方案。
JSON v2 和 jsontext 分工不一样
简单理解，encoding/json/v2 仍然偏向 Go struct 和 JSON 对象之间的映射；encoding/json/jsontext 更接近底层 token 读写，适合你想自己控制流式解析、校验、转换的场景。
如果你的业务只是普通 API DTO，优先看 v2 的行为和选项。如果你在做网关、数据清洗、日志管道、大 JSON 流处理，jsontext 才更值得认真研究。
几个行为变化要特别小心
JSON v2 更强调数据正确性。比如 UTF-8、重复对象成员名、字段匹配规则这些地方，和老的 encoding/json 可能不完全一样。对新项目这是好事，对老项目就是迁移风险。
最典型的是第三方回调。你以为对方发来的是标准 JSON，实际上可能有重复 key、奇怪编码、大小写混乱字段。v1 也许默默接受了，v2 可能更早暴露问题。这个变化本身不坏，但上线前必须知道哪些输入会被拒绝。
// 迁移前先做影子对比，不要直接替换生产路径
func decodeWithShadow(raw []byte, dst any) error {
err1 := json.Unmarshal(raw, dst)
var shadow any
err2 := jsonv2.Unmarshal(raw, &shadow)
if (err1 == nil) != (err2 == nil) {
slog.Warn("json behavior differs",
"v1_err", err1,
"v2_err", err2,
)
}
return err1
}
我会怎么做迁移评估
第一步只选一条热点路径，比如订单详情接口的响应编码，或者消息消费里的大 JSON 解码。第二步准备真实样本，别只用手写的小 JSON。第三步同时跑 benchmark、兼容性测试和线上影子日志。
如果只是为了快，我会要求看到明确数据：分配次数下降多少、CPU 降多少、P99 有没有变化。没有数据的“听说更快”，在生产里不算理由。
字段设计比换库更重要
很多 JSON 问题不是库导致的，而是结构体设计不清楚。比如 omitempty 把零值和未传混在一起，业务上却需要区分“没传”和“传了 0”。这种问题换成 v2 也不会自动变好。
我更建议在 DTO 层把语义说清楚：可选字段用指针或专门的 nullable 类型；内部领域模型不要直接暴露给外部 JSON；第三方回调单独定义 input struct，不要复用数据库模型。
流式场景要认真看 jsontext
如果你的服务要处理几十 MB 甚至更大的 JSON，直接 Unmarshal 到一个大结构里可能会造成内存峰值很高。jsontext 的价值在于你可以按 token 流式处理，只保留需要的字段。
这种写法代码会更啰嗦，所以我不会在普通接口里滥用它。但在日志清洗、数据导入、网关转发、只抽取少数字段的大文档处理里，它很值得评估。
我的 JSON v2 review 清单
- 这条路径是否真的是 JSON 编解码热点，有 pprof 或 benchmark 证明吗？
- 是否用真实线上样本做过 v1/v2 行为对比？
- 是否评估过重复 key、大小写字段、非法 UTF-8、数字精度这些兼容性问题？
- DTO 是否区分了未传、零值、空字符串、空数组这些业务语义？
- 大 JSON 是否需要流式处理，而不是一次性 Unmarshal？
- 是否把实验能力限制在小范围路径，避免一次性全局替换？
- 上线后是否有错误率、解码失败、P99、CPU 和分配指标观测？
最后聊两句
JSON v2 值得关注，但我不建议把它当成“性能银弹”。它更像是 Go 团队对 JSON 长期问题的一次系统性整理：更清晰的语义、更严格的输入、更好的流式能力，以及给未来迁移留下空间。
我的建议很简单：新项目可以提前研究，老项目先从热点路径做影子对比。真正靠谱的迁移，不是把 import 一改就上线，而是拿数据证明它更快，拿样本证明它兼容，拿监控证明它没伤到线上。
