编程 Go 1.27 的 JSON v2:默认区分大小写、重复键报错,nil 切片会变成 []

2026-11-17 20:01:45

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/jsonencoding/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}

把差异写成接口测试

  1. 先升级工具链,跑现有测试。保持原有导入,重点检查自定义编解码方法和错误处理。需要区分错误类型时优先用 errors.As 等机制,避免绑定完整错误文本。v1 API 背后的新实现加快了解码,可以先用业务数据跑基准测试,再决定是否迁移 API。

  2. 对请求同时断言错误和字段值。用表驱动测试覆盖正常字段、大小写变体、重复键、未知字段和必填字段缺失。如果接口要求精确字段名并且允许拒绝未知字段,可以用 jsonv2.RejectUnknownMembers(true) 让拼错的字段直接报错,同时保留业务层的必填校验。如果旧客户端依赖宽松匹配,可评估对单个字段使用 case:ignore。它还会忽略连字符和下划线,启用前应把这些变体写进测试。

  3. 对响应断言字段缺失、null 和空集合。这三种形态在前端渲染、生成的 SDK 或补丁协议里可能各有含义。若现有契约要求保留 nil 切片或 nil map 的 null,可以分别使用 jsonv2.FormatNilSliceAsNull(true) 和 jsonv2.FormatNilMapAsNull(true)。先选择一个调用方明确的端点灰度,观察该端点的解码失败率和客户端错误,再逐步扩大范围。

迁移节奏

第一步只升级工具链,保留原有 encoding/json 导入,让 v1 API 背后的新实现先跑一遍业务数据;第二步才显式切换到 encoding/json/v2 并修改接口行为。灰度时从调用方明确的单个端点开始,观察解码失败率和客户端错误,再逐步扩大。回滚用 GOEXPERIMENT=nojsonv2,它是过渡手段,不是长期方案。

参考

复制全文 生成海报 Go JSON API 迁移

推荐文章

程序员茄子在线接单