为什么一个 JSON 库，Go 团队花了六年才重写完？
内容提要
Go 1.27 正式稳定发布 encoding/json/v2 与 jsontext，结束近六年重构。因 Go 1 兼容承诺，旧版无法直接修复，故另设 v2。新架构将 JSON 语法解析与 Go 类型映射分离，旧版由 v2 底层驱动，存量代码无需修改即可受益，反序列化部分场景最高提速 10 倍。官方强调旧版不废弃，并提供迁移指南。
延伸解读
兼容承诺如何塑造重构路径
Go 1 的向后兼容承诺使旧版 encoding/json 的既有行为成为事实契约，例如大小写不敏感匹配、nil slice 编码为 null、接受非法 UTF-8。直接修正这些行为会破坏下游业务，因此团队选择另设 v2 命名空间，而非在旧 API 上打补丁。这解释了六年周期的根源：重构难点不在 JSON 语法本身，而在如何在不破坏存量生态的前提下引入更合理的行为。
双层架构带来的实际变化
v2 将 JSON 处理拆为 jsontext 和 encoding/json/v2 两层。jsontext 只负责语法解析、Token 流式读写和编解码，不依赖 Go 反射；v2 层负责 Go 类型映射、自定义 Marshaler 和可配置 Options。这种分离让语法层可作为独立组件使用，语义层能更灵活地实现类型映射，两层也可独立演进。对读者而言，这意味着未来 JSON 相关能力扩展不必再受旧版交织逻辑的限制。
旧版不废弃，底层统一驱动
旧版 encoding/json 不会被废弃，而是由 v2 底层实现驱动，形成“底层统一、行为分流”的共存方式。存量项目无需修改代码即可获得反序列化部分场景最高 10 倍性能提升，并可通过 Options 逐步选择新行为。官方还提供 MarshalJSONTo 和 UnmarshalJSONFrom 接口，使仍走 v1 调用的项目也能在底层受益。这种设计降低了迁移成本，避免把重构代价转嫁给使用者。
性能收益有边界，迁移不必急
官方基准显示，v2 的 Marshal 性能总体与 v1 接近，Unmarshal 在部分场景最高提升 10 倍，但部分场景仍慢于 v1，后续 Go 1.28 还会继续优化。因此读者不应把 v2 简单理解为全面提速，而应结合自身序列化模式评估。官方明确旧版继续支持并提供迁移指南，现有项目无需急于全量迁移，可先关注底层统一带来的维护与性能收益。
Q&A
Go 1.27 中 encoding/json/v2 和 jsontext 正式稳定发布了吗？
是的，Go 1.27 正式将 encoding/json/v2 和 encoding/json/jsontext 标记为稳定可用，结束了近六年的重构。
为什么 Go 团队不直接修复旧版 encoding/json，而要另起 v2？
因为 Go 1 有严格的向后兼容承诺，旧版的大小写模糊匹配、nil slice 编码为 null、接受非法 UTF-8 等行为已成为事实上的 API 契约，直接修改会破坏大量下游业务，所以必须另设 v2 命名空间。
JSON v2 的双层架构具体是怎么划分的？
JSON v2 将 JSON 处理拆成两层：encoding/json/jsontext 负责 JSON 语法层面的解析、Token 流式处理和编解码，不依赖 Go 反射；encoding/json/v2 负责 JSON 与 Go 类型之间的语义映射，包括 struct 映射、自定义 Marshaler 和可配置 Options。
旧版 encoding/json 会被废弃吗？现有项目需要改代码才能受益吗？
旧版 encoding/json 不会被废弃，而是由 v2 的底层实现驱动。存量项目无需修改一行代码即可获得反序列化部分场景最高 10 倍的性能提升和持续维护保障。
JSON v2 相比旧版在性能上有多大提升？
根据官方基准测试，v2 的 Marshal 性能总体与 v1 接近，而 Unmarshal 在部分场景下最高可达 10 倍性能提升。不过部分场景仍慢于 v1，后续 Go 1.28 还会继续优化。
现在需要把项目迁移到 JSON v2 吗？官方提供了什么支持？
目前不需要急着迁移。Go 官方提供了专门的迁移指南，旧版 API 也会继续得到支持，开发者可以按需逐步迁移。
