JSON 空值语义

我在接口联调时遇到过一个很容易被忽略的差异：Go 里的两个“没有元素”的 slice，返回给前端后可能一个是 null，另一个是 []。这不是 JSON 库随机变化，而是 slice 本身是否为 nil。

使用标准库 encoding/json 时，nil slice 默认编码为 null，初始化但长度为 0 的空 slice 默认编码为 []。如果结构体字段带 omitempty，这两种空值都会被省略。

官方资料：https://pkg.go.dev/encoding/json

先确认 null 和 [] 分别从哪里来

先不要从前端现象倒推业务问题，直接把切片状态和序列化结果放在一起看。下面的代码只比较长度都为 0 的两种 slice；代码中的中文注释说明了每个变量为什么存在。

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    var nilItems []string
    emptyItems := make([]string, 0)

    // 两个切片长度和容量都为 0，但只有 emptyItems 的底层切片状态已初始化。
    values := map[string][]string{
        "nilItems":   nilItems,
        "emptyItems": emptyItems,
    }

    // Marshal 返回 JSON 字节；这里检查错误，避免把序列化失败当成空值结果。
    data, err := json.Marshal(values)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}

关键输出是 nilItems 对应 null，emptyItems 对应 []。标准库文档明确规定：数组和 slice 默认编码为 JSON 数组，但 nil slice 是一个例外，会编码为 JSON 的 null 值。

为什么长度一样，接口结果却不同

slice 可以先理解成“指向底层数组的描述”。nil slice 没有指向底层数组；通过 make([]string, 0) 得到的空 slice 虽然长度和容量也可能都是 0，但它的 slice 值已经不是 nil。

package main

import "fmt"

func main() {
    var nilItems []string
    emptyItems := make([]string, 0)

    // len 只能说明当前元素个数，不能区分 nil 与非 nil 的空 slice。
    fmt.Println(len(nilItems), len(emptyItems))
    fmt.Println(nilItems == nil, emptyItems == nil)
}

因此，排查时不要只打印 len(items)。如果接口契约要求“没有数据也返回数组”，判断条件应是 items == nil，而不是 len(items) == 0。反过来，如果业务把“尚未加载”与“已加载但没有结果”区分开，null 和 [] 就可以保留为两种不同状态。

把切片状态映射成接口契约

结构体字段是 API 输出的常见边界。默认标签会把两种状态原样暴露出去；omitempty 则会把空字段从对象里拿掉。下面把三种策略放在一个结构体里，便于对照。

package main

import (
    "encoding/json"
    "fmt"
)

type Response struct {
    // 默认字段保留 nil 与空 slice 的差异，分别得到 null 和 []。
    Items []string `json:"items"`
    // omitempty 会省略 nil 或长度为 0 的 slice。
    Optional []string `json:"optional,omitempty"`
}

func main() {
    result := Response{
        Items:    nil,
        Optional: make([]string, 0),
    }

    // 只把结构体编码一次，观察字段是否存在以及值是什么。
    data, err := json.Marshal(result)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}

这个结果会保留 items:null，而 optional 不会出现在 JSON 对象中。标准库对 omitempty 的定义包含 nil 指针、nil interface，以及长度为 0 的数组、slice、map 或 string，所以它不是“把 null 改成 []”，而是直接移除字段。

线上返回前怎样统一空值策略

我通常先问调用方要的是“状态”还是“容器”。如果调用方只希望遍历列表，统一成 [] 最省心；如果调用方需要区分“未加载”和“加载后无数据”，就保留 null 与 [] 的差异；如果字段本身可选，才考虑 omitempty。

策略一：初始化为可返回的空数组

func listNames() []string {
    // 先建立非 nil 的空 slice，让没有结果时仍返回 []。
    names := make([]string, 0)
    return names
}

这种写法适合“列表字段永远存在”的接口。也可以在组装响应对象的最后统一处理，但要把规则放在一个明确的边界层，避免每个查询函数各写一套。

策略二：保留 null 与 [] 的业务含义

type Result struct {
    // nil 表示尚未查询或没有装载结果，非 nil 空 slice 表示查询完成但无记录。
    Items []string `json:"items"`
}

func newLoadedEmptyResult() Result {
    // 显式初始化，告诉调用方这是“已完成且为空”。
    return Result{Items: make([]string, 0)}
}

此时要把约定写进接口文档或字段注释，否则前端很容易把 null 当成异常，把 [] 当成正常结果，最后又在各自的代码里做不一致的兼容。

策略三：字段可选时使用 omitempty

如果字段没有结果时不应该出现在响应中，可以使用 json:"items,omitempty"。但要注意，这会同时隐藏 nil 和空 slice；如果两者的业务意义不同，就不能用这个标签代替状态建模。

回滚和告警确认应该看什么

如果上线后调用方突然报“期望数组却收到 null”，优先回看响应结构的初始化路径，而不是先改前端解析。通常可以按下面的顺序处理：

回滚时也只回滚“空值策略”的改变，不要为了修复一个字段把整个响应对象改成自定义序列化。复盘项可以保留三条：接口文档是否写清 null 与 []、单元测试是否覆盖 nil 和 empty 两个输入、响应组装层是否只有一个归一化入口。

最后记住这张速查表

这类问题的核心不是记住某个输出，而是先确定接口契约：要不要区分“没有加载”和“加载完成但为空”，要不要保留字段。如果只需要稳定的列表类型，就在响应边界统一返回空 slice；如果需要表达状态，就保留 nil 与 empty 的差异并写进文档。

相关问题

• 为什么只判断 len(slice) 不能决定返回 null 还是 []？因为 nil slice 与非 nil 的零长度 slice 都可能有长度 0，必须额外判断 slice == nil。
• omitempty 会把 null 转成 [] 吗？不会。它会在字段为空时省略字段。
• 接口一定要禁止 null 吗？不一定，关键是调用方是否能理解这个状态以及文档是否明确。