Go 1.27 的 JSON v2:默认区分大小写、重复键报错,nil 切片会变成 []
一个 Go API 接收 {"NAME":"Ada"},请求结构体声明的标签是 json:"name"。旧代码仍能拿到 Ada。把导入换成 encoding/json/v2 后,同一个请求默认解码成功,Name 却是空字符串。只检查解码错误的测试会漏掉这次变化。
Go 团队在 11 月 10 日发布了 Go 1.27.4,同日回顾了过去一年标准库的更新(Go 发布历史、Go 1.27 发布说明、Go 17 周年回顾)。对维护 HTTP API 的团队,JSON v2 值得单独看。Go 1.27 已经让旧的 encoding/json API 使用新实现,同时保留 v1 的编解码语义,错误文本可能变化。显式改用 encoding/json/v2 才会采用下文的 v2 默认规则。升级工具链和修改接口行为可以分两次发布。
四处会影响 API 契约的差异
| 场景 | encoding/json | encoding/json/v2 |
|---|---|---|
| 输入字段是 NAME,结构体标签是 name | 可以忽略大小写匹配 | 默认按大小写精确匹配,未识别的字段默认被忽略 |
| 同一对象内有两个 name 键 | 接受。对于示例中的字符串字段,后值覆盖前值 | 默认返回错误 |
| 响应中的 []string(nil) 或 map[string]string(nil),未加省略标签 | 输出 null | 分别输出 [] 和 {} |
| int 为 0,标签使用 omitempty | 省略该字段 | 保留该字段并输出 0 |
最后一项也影响带 omitempty 的 false。v2 按编码后的 JSON 判断是否为空,空值包括 null、空字符串、空数组和空对象。希望按 Go 零值省略普通整数或布尔字段时,可以用 omitzero。对于集合,omitzero 只省略 nil 切片或 nil map,长度为零但已初始化的集合会保留。参考 v1 兼容性说明、v2 包文档,底层编解码见 jsontext。
用同一组数据跑两套 API
用 Go 1.27 将代码保存为 main.go,运行 go run main.go。
package main
import (
jsonv1 "encoding/json"
jsonv2 "encoding/json/v2"
"fmt"
"log"
)
type request struct {
Name string `json:"name"`
}
type response struct {
Items []string `json:"items"`
Count int `json:"count,omitempty"`
}
func main() {
for _, input := range []string{
`{"NAME":"Ada"}`,
`{"name":"Ada","name":"Grace"}`,
} {
var oldRequest, newRequest request
oldErr := jsonv1.Unmarshal([]byte(input), &oldRequest)
newErr := jsonv2.Unmarshal([]byte(input), &newRequest)
fmt.Printf("%s\n", input)
fmt.Printf(" v1 name=%q, error=%t\n", oldRequest.Name, oldErr != nil)
if newErr != nil {
fmt.Println(" v2 rejected the input")
} else {
fmt.Printf(" v2 name=%q, error=false\n", newRequest.Name)
}
}
oldJSON, err := jsonv1.Marshal(response{})
if err != nil {
log.Fatal(err)
}
newJSON, err := jsonv2.Marshal(response{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("v1 response: %s\nv2 response: %s\n", oldJSON, newJSON)
}
输出:
{"NAME":"Ada"}
v1 name="Ada", error=false
v2 name="", error=false
{"name":"Ada","name":"Grace"}
v1 name="Grace", error=false
v2 rejected the input
v1 response: {"items":null}
v2 response: {"items":[],"count":0}
把差异写成接口测试
先升级工具链,跑现有测试。保持原有导入,重点检查自定义编解码方法和错误处理。需要区分错误类型时优先用
errors.As等机制,避免绑定完整错误文本。v1 API 背后的新实现加快了解码,可以先用业务数据跑基准测试,再决定是否迁移 API。对请求同时断言错误和字段值。用表驱动测试覆盖正常字段、大小写变体、重复键、未知字段和必填字段缺失。如果接口要求精确字段名并且允许拒绝未知字段,可以用
jsonv2.RejectUnknownMembers(true)让拼错的字段直接报错,同时保留业务层的必填校验。如果旧客户端依赖宽松匹配,可评估对单个字段使用case:ignore。它还会忽略连字符和下划线,启用前应把这些变体写进测试。对响应断言字段缺失、null 和空集合。这三种形态在前端渲染、生成的 SDK 或补丁协议里可能各有含义。若现有契约要求保留 nil 切片或 nil map 的 null,可以分别使用
jsonv2.FormatNilSliceAsNull(true)和jsonv2.FormatNilMapAsNull(true)。先选择一个调用方明确的端点灰度,观察该端点的解码失败率和客户端错误,再逐步扩大范围。
迁移节奏
第一步只升级工具链,保留原有 encoding/json 导入,让 v1 API 背后的新实现先跑一遍业务数据;第二步才显式切换到 encoding/json/v2 并修改接口行为。灰度时从调用方明确的单个端点开始,观察解码失败率和客户端错误,再逐步扩大。回滚用 GOEXPERIMENT=nojsonv2,它是过渡手段,不是长期方案。