Go 空切片转 JSON 为什么有时是 null 有时是空数组

Go 空切片转 JSON 出现 null 或 []，通常不是序列化器随机变化，而是两个 slice 的 nil 状态不同：nil slice 的长度可以是 0，但没有底层切片；用 make([]T, 0) 得到的是非 nil、长度同样为 0 的空 slice。标准库 encoding/json 会把前者编码为 null，后者编码为空数组 []。

先把 nil 切片和空切片分开

这两个值的长度都为 0，但状态并不相同。排查时不要只打印长度，同时打印 nil 判断：

package main

import (
	"encoding/json"
	"fmt"
)

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

	// len 只能说明元素数量，== nil 才能说明 slice 是否为 nil。
	for name, items := range map[string][]string{
		"nilItems":   nilItems,
		"emptyItems": emptyItems,
	} {
		data, err := json.Marshal(items)
		if err != nil {
			panic(err)
		}
		fmt.Printf("%s: len=%d nil=%t json=%s\\n", name, len(items), items == nil, data)
	}
}

输出的关键差异是：nilItems 为 len=0、nil=true、json=null，emptyItems 为 len=0、nil=false、json=[]。这正是“查不到记录”时接口结果不一致的常见来源。

从 Go 值到 JSON 的映射

encoding/json 的默认规则很直接：普通 slice 按数组编码，nil slice 特殊编码为 JSON null。因此“没有元素”和“没有这个集合值”在 JSON 层可能被表达成不同语义。

这个差异也会影响接口消费者：有些前端代码可以直接遍历 []，却把 null 当作缺少数据；而数据库查询、缓存读取或错误兜底路径又很容易留下 nil slice。接口设计时应先决定集合字段的契约，再决定 Go 侧的初始化方式。

接口字段该选 null、[] 还是直接省略

如果字段代表“列表结果”，并且调用方总是期待数组，建议在响应组装阶段把 nil 归一化为空数组：

package main

import "encoding/json"

type Response struct {
	Items []string `json:"items"`
}

func buildResponse(items []string) Response {
	if items == nil {
		// API 契约要求集合字段始终存在，因此把 nil 转成空数组。
		items = make([]string, 0)
	}
	return Response{Items: items}
}

func encodeResponse(items []string) ([]byte, error) {
	// 先统一值，再交给 json.Marshal，避免不同分支产生不同协议。
	return json.Marshal(buildResponse(items))
}

如果“没有值”本身有业务含义，例如未加载、无权限或尚未计算，则可以保留 null，但应在接口文档中明确。若字段只在有内容时返回，才使用 json:"items,omitempty"；在 v1 语义下，nil slice 和长度为 0 的 slice 都会被 omitempty 省略，不能用它来稳定输出 []。

排查与落地的推荐流程

遇到线上返回值不稳定时，可以按下面的顺序定位：

1. 在编码前记录 len(items) 和 items == nil，确认差异发生在数据组装还是 JSON 编码阶段。
2. 检查所有分支，包括“查不到数据”“发生错误”“缓存未命中”和“默认响应”，是否返回了不同的 slice 状态。
3. 根据契约选择策略：列表字段通常归一化为 []，三态字段保留 null，可选字段才使用 omitempty。
4. 把归一化放到响应构造函数或 DTO 层，避免每个 handler 单独写一遍，减少后续回归。

常见问题

空 slice 和 nil slice 的 len 为什么一样？

两者都没有元素，所以 len 都是 0；它们的区别在于 slice 是否为 nil，使用 items == nil 判断。

把 nil slice 转成空数组需要复制元素吗？

不需要。make([]T, 0) 只建立一个非 nil 的空 slice，适合在响应边界统一 JSON 形状。

omitempty 能让空 slice 输出 [] 吗？

不能。omitempty 的作用是省略空值；要保留字段并输出 []，应先把 nil slice 初始化为空 slice，并且不要加该标签。

可继续查阅 Go 官方 encoding/json 文档中 Marshal 和结构体字段标签的说明。