---
title:"Go 终于有了新的 JSON API:v1 的十五年旧账,v2 一次结清"date:2026.11.05category:[编程, 行业观察]tags:[go, json, golang, stdlib, performance, hacker-news]status:published
---

Go 终于有了新的 JSON API:v1 的十五年旧账,v2 一次结清

Go 1.27 带来了稳定的 encoding/json/v2:六年打磨、两层重构,修掉了 v1 十五年攒下的行为缺陷,还把 Unmarshal 速度提到了 10 倍——但 MarshalIndent 没了,迁移也不是无痛的。

2026.11.05·6 min read·9.9KB
// tl;dr: generating summary...

Go 终于有了新的 JSON API:v1 的十五年旧账,v2 一次结清

11 月 4 日,Go 团队在官方博客宣布:经过六年打磨,新的 encoding/json/v2 和 encoding/json/jsontext 正式随 Go 1.27 稳定发布。JSON 是互联网上最流行的数据格式,也是 Go 程序读写最频繁的东西——而标准库里的 encoding/json 从 Go 1.0 之前就存在了,十五年没动过根基。帖子发到 Hacker News,344 分、175 条评论,讨论很快从"终于等到了"滑向了更实际的问题:旧代码怎么办、性能到底快多少、以及——MarshalIndent 去哪了?我请来老朋友顾言,他做云原生基础设施,整天跟 Go 服务端代码打交道,聊聊这次 v2 到底改了什么,值不值得迁。

本文由每日自动管线生成:选题与素材来自 Hacker News 公开讨论,访谈内容由 AI 基于原文整理,嘉宾为角色设定,观点不代表任何真实人物。

小听: 顾言,先说最基本的:encoding/json 用了十五年,大家天天都在用,它到底有什么问题,非得另起一个 v2?

顾言: 问题分三类,官方博客列得挺实在。第一类是行为缺陷——有些默认行为今天看就是错的。比如 v1 接受无效的 UTF-8,按 RFC 8259 这本来就该报错,结果却是静默地"修"过去,下游拿到被污染的数据都不知道;再比如 JSON 对象里出现重复的字段名,v1 随手取一个,2017 年就有人拿这个在安全场景里做过文章(CVE-2017-12635)。还有更日常的:nil 切片会被 marshal 成 null,而对面很多语言的 JSON 库根本不接受 null 出现在期望数组的位置。大小写不敏感的字段匹配也是个隐患——既出乎意料,又有安全风险,还拖慢性能。

小听: 听起来都是能修的 bug,为什么不直接在 v1 里修掉?

顾言: 因为 Go 1 兼容性承诺。v1 的每一个怪行为,背后都有成千上万个程序在依赖。官方说得很坦白:MarshalJSON 在指针接收者上的调用不一致,明明是个 bug,但就是修不了——太多应用依赖现有行为了。加个 MarshalV2 这样的新函数名呢?那等于在同一个包里再建一套平行命名空间,跟另起 v2 没区别。所以结论是:v1 动不了,只能在旁边另开一个 encoding/json/v2,在新名字空间里把账一次结清。

小听: v2 的设计里有个新面孔:encoding/json/jsontext。它到底是干嘛的?

顾言: 这是整个重构里最漂亮的一刀。Go 团队把 JSON 处理拆成两层:语法层只管"这串字符是不是合法 JSON",语义层管"JSON 值和 Go 值怎么对应"。jsontext 就是语法层——Encoder/Decoder、Value、Token,只处理 token 流,不碰反射。v2 坐在它上面做 marshal/unmarshal。分层的好处是,以前 v1 里很多性能问题根子都在"语法和语义搅在一起":MarshalJSON 必须先返回完整的 []byte,库还得验证一遍、再按缩进重排一遍;UnmarshalJSON 收到值之前,库得先把整个值解析一遍定边界,方法自己又解析一遍。递归调用时性能直接变成平方级。v2 新增的 MarshalJSONTo 和 UnmarshalJSONFrom 直接对着 Encoder/Decoder 流式读写,这些重复劳动就全省了。

小听: 具体到行为上,v2 改了哪些东西?开发者迁移时最容易踩到什么?

顾言: 清单不长,但每条都可能让现有测试变红:无效 UTF-8 现在报错;重复字段名现在报错;nil 切片和 nil map 默认 marshal 成 [] 和 {},不再是 null;字段匹配改成大小写敏感;omitempty 被重新定义——只有编码后是"空 JSON 值"(null、""、[]、{})的字段才省略;time.Duration 现在没有默认表示,序列化直接报错,得由调用方显式选一种表示。好消息是,每条行为差异都有对应的选项可以调回去,迁移可以是渐进的:json.Marshal(..., json.DefaultOptionsV2(), jsontext.AllowDuplicateName(true)) 就是"全用 v2,只保留重复名宽容"的意思,反过来也可以先全用 v1 语义、只收紧重复名这一条。

小听: 性能这块官方给了数字吗?

顾言: 给了,而且很克制。Marshal 基本和 v1 持平,有时快一点有时慢一点;Unmarshal 是重头戏,基准测试里最高快了 10 倍。但这个 10 倍有个前提:现有的 Marshaler/Unmarshaler 实现得升级成 MarshalerTo/UnmarshalerFrom 才能吃到流式的红利。官方举了个真实例子:Kubernetes 的 kube-openapi 在 UnmarshalJSON 里递归解析 OpenAPI 规范,性能被拖得很惨,换成 UnmarshalJSONFrom 之后提升了几个数量级。所以 v2 的性能故事不是"换个 import 就快 10 倍",而是"新接口给了你快 10 倍的可能"。

一台布满灰尘的老式分拣机在昏暗机房里运转,缠绕的线缆与磨损的齿轮沐浴在一束冷光中

十五年的旧包袱,不是一次重构就能甩掉的——但总得有人先动手。

小听: 评论区有个抱怨点赞很高:有人说 v2 把 MarshalIndent 删了,调试时想打印一段可读 JSON 变得特别麻烦。你怎么看?

顾言: 这是 CamouflagedKiwi 的帖子,他说得挺实在:新写法"超级复杂还不直观",随手 dump 一段可读 JSON 的体验变差了。不过楼下马上有人给了替代方案:jsontext.Value(b).Indent(),两行就能搞定。这件事其实挺能说明 v2 的取舍——它把很多"顺手"的功能挪到了更底层、更组合式的位置。功能没丢,只是从"一个顺手函数"变成了"两个底层调用拼起来"。对库作者这是好事,对随手写脚本的人,确实多了一步。

小听: 还有一条争论挺有意思:有人问为什么 Marshal 要返回 error——"不能 marshal 的输入明明是代码 bug,凭什么在运行时才报错?"

顾言: 这条 thread 吵了十几层。发帖的人觉得,Marshal 失败的唯一原因是输入类型不可 marshal,这应该是编译期错误,像 int + str 那样直接不让编译。反驳的观点也很硬:JSON 本质上是运行时输入,编译器不知道用户会传什么进来;而且 Marshal 接口的意义就是可复用,你不能要求编译器预知所有数据。最后有人总结得到位:这不是类型系统的问题,是数据来源的问题——想在编译期保证 JSON 类型安全,就别用 Marshal 接口。v2 没有动这条设计,说明 Go 团队也认同:这个 error 是 API 语义的一部分,不是历史包袱。

小听: 兼容性这块,官方是怎么保证 v1 和 v2 不打架的?

顾言: 这是 v2 设计里最聪明的一点:v1 现在是在 v2 之上实现的。Go 团队把 v2 的每个行为差异都做成一个选项,v1 就是"v2 加上一整套 v1 兼容选项"。所以两个方向都通:v2 能识别老代码的 MarshalJSON 方法,v1 反过来也能识别新代码的 MarshalJSONTo。依赖混用两个版本的包不会炸,生态可以慢慢迁,不用逼所有人同一天升级。新的 struct tag(比如 embed)和新方法会自动惠及 v1 用户——因为底层已经是同一套实现了。

小听: 这事从 2020 年就开始了,整整六年。为什么一个 JSON 库要花六年?

顾言: 时间线官方博客写得很细:2020 年底,维护者 Daniel Martí 先写了份"假如重做 v2 该长什么样"的草稿;Joe Tsai 做完 protobuf 的 Go API 之后,发现 protojson 不得不用自己的 JSON 实现,因为 encoding/json 既跟不上 protobuf 要求的严格标准,也做不了流式序列化,两人一拍即合开始做原型。之后是公开会议、GopherCon 演讲、2023 年底的讨论帖、2025 年初的正式提案、Go 1.25 作为实验特性放出来给所有人试用,最后才在 Go 1.27 稳定。六年里换了七八个核心贡献者,大部分都不是 Google 员工。标准库的改动就是这样——改错了影响的是全世界所有 Go 程序,所以宁可慢,不能错。

小听: 最后给读者一个实在的建议:现在该迁吗?

顾言: 分三档。新项目直接上 v2,没什么可犹豫的,默认行为更安全,Unmarshal 更快,选项也更灵活。老项目不用急,v1 会无限期支持,官方原话是"永远不需要迁移"。想迁的,先从测试覆盖好的服务开始,把行为差异清单当检查表逐条过一遍,尤其注意 time.Duration 和大小写敏感这两处——它们是最容易在生产环境悄悄变行为的。还有一个小提醒:如果你维护的库被很多人依赖,优先把自定义的 MarshalJSON/UnmarshalJSON 升级成流式版本,你的下游会因此快很多。v2 这次最大的意义可能不是快了多少,而是 Go 终于有了一个能继续演进十五年的 JSON 底座。

两层半透明玻璃板上下叠放,发光的数据流穿过下层、从上层以整齐的方块形态涌出

语法和语义分开之后,JSON 终于有了一个能再走十五年的底座。

参考链接

// related: searching nearest posts...
# comments