Go encoding/json/v2 怎样让 nil map 编码为 JSON null

如果旧接口约定 nil map 输出为 null，迁移到 Go 的 encoding/json/v2 后要显式补上 json.FormatNilMapAsNull。v2 的默认规则是把 nil map 编码成空 JSON 对象 {}，这不是 map 初始化状态改变，而是序列化语义改变。

官方文档：https://pkg.go.dev/encoding/json/v2

迁移说明：https://go.dev/doc/jsonv2-migration

最小修复是在 json.Marshal 中传入 json.FormatNilMapAsNull(true)。它只改变 nil map 的 JSON 表示；非 nil map 仍按对象编码，字段级 format:"emitempty" 还可以覆盖全局设置。

先确认 v1 与 v2 的默认输出差异

旧的 encoding/json 语义会把 nil map 编码成 null；encoding/json/v2 默认把它编码成空对象。对前端来说，null 与 {} 可能分别代表“没有值”和“有一个空对象”，因此不能只看 Go 端类型一样就认为接口兼容。

这里要分清三件事：map 变量是否为 nil、v2 的默认选项是什么、调用时是否显式传入了覆盖选项。非 nil map 即使没有键，也仍然是一个空对象；只有 nil map 才会触发这个默认差异。

用 FormatNilMapAsNull 保持旧接口语义

需要兼容旧接口时，把选项放在编码调用处即可：

package main

import (
    "fmt"
    "log"

    "encoding/json/v2"
)

func main() {
    var labels map[string]string // nil map 用来表示“没有标签数据”

    body, err := json.Marshal(labels, json.FormatNilMapAsNull(true)) // 只把 nil map 改编码为 null
    if err != nil {
        log.Fatal(err) // 编码失败时立即停止，避免发送不完整响应
    }

    fmt.Println(string(body)) // 预期的静态示例结果是 null
}

FormatNilMapAsNull(true) 是一个可传入 v2 编码函数的选项。不要为了得到 null 先把 map 转成字符串，也不要手动拼 JSON；那样会绕开 JSON 编码器对键和值的处理。

如果项目中已经集中管理编码选项，也可以把这个选项与其他 v2 选项一起传入。选项按传入顺序覆盖，后面的设置优先；因此迁移时要检查公共封装函数是否在调用链后面又传入了相反的设置。

需要局部覆盖时看字段 format 标签

全局选项适合一组接口都遵循旧契约的场景；如果只有某个字段需要空对象，而其他 nil map 仍应输出 null，可以在结构体字段上使用格式标签。v2 的格式标签用 emitempty 表示 nil map 使用空对象语义，具体写法如下：

type Profile struct {
    Extra map[string]string `json:"extra,format=emitempty"` // 这个字段保持空对象语义
    Meta  map[string]string `json:"meta"`                   // 其他字段遵循调用处的全局选项
}

字段级规则解决的是“同一响应内不同字段的表示不同”这个问题。它不是把 nil map 变成非 nil map，也不会影响 map 的读写行为。字段标签与调用处选项同时存在时，应以官方文档定义的字段格式和选项优先级为准，并通过接口样例确认最终 JSON。

迁移后按这份清单回归

1. 找出所有返回 map 的公共响应结构，标记旧接口明确要求 null 的字段。
2. 确认编码入口使用的是 v1 还是 v2，不要只依据 import 别名判断。
3. 对 nil map、空但已初始化的 map、包含一项的 map 分别准备 JSON 契约样例。
4. 若只需兼容少数字段，优先评估字段级格式；若整组接口统一兼容，再在公共编码入口传选项。
5. 不要把本题与 nil slice 混用。slice 对应的是 FormatNilSliceAsNull，应单独确认契约。

一句话总结：v2 默认把 nil map 当成空对象输出，兼容旧的 null 约定就传 json.FormatNilMapAsNull(true)，需要局部差异时再用字段 format 标签收窄影响范围。

相关问题

非 nil 的空 map 会被编码成 null 吗？

不会。非 nil 空 map 是一个已初始化但没有键的 map，仍按 JSON 空对象语义处理；本题的开关针对 nil map。

这个选项会改变 JSON 解码吗？

文章讨论的是编码路径。解码时应另外确认 JSON null 如何合并到目标 map，以及已有值是否需要先清理。

为什么不直接初始化 map？

初始化会改变 Go 值本身，可能影响业务层对“缺失”和“空集合”的判断。选项只改变传输表示，更适合接口兼容迁移。