Go nil slice 和空 slice 序列化结果为什么不一样

Go 接口里同一个切片字段一会儿返回 null，一会儿返回 []，通常不是 JSON 库随机了，而是 Go 值的状态不同：nil slice 和“长度为 0 但已经分配”的空 slice 不是同一个值。传统 encoding/json（v1）会把前者编码成 null，后者编码成空数组 []；如果项目切换到 encoding/json/v2，默认语义又不同，必须先确认实际导入的包。

先把 nil slice 和空 slice 摆在一起看

slice 的 len 都可以是 0，但 nil 状态仍然不同。append 对两者都安全，所以问题经常直到序列化响应时才暴露。下面的结构体模拟一个列表接口的返回值。

package main

import (
    "encoding/json"
    "fmt"
)

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

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

    // 两个切片长度都为 0，但 nil 判断结果不同。
    fmt.Println(nilItems == nil, len(nilItems))
    fmt.Println(emptyItems == nil, len(emptyItems))

    for _, items := range [][]string{nilItems, emptyItems} {
        body, err := json.Marshal(Response{Items: items})
        if err != nil {
            // 序列化失败时立即返回，避免把不完整响应发给客户端。
            panic(err)
        }
        fmt.Println(string(body))
    }
}

在传统 encoding/json v1 下，输出分别是 {"items":null} 和 {"items":[]}。所以 len(items) == 0 只能说明没有元素，不能说明客户端最终会收到空数组。

为什么 omitempty 又会让结果消失

如果字段写成 json:"items,omitempty"，传统 v1 会把 nil slice 和长度为 0 的 slice 都视为空值，于是整个 items 字段被省略。此时结果不再是 null 或 []，而是没有这个键。

因此先定 API 契约，再决定 Go 初始化方式。列表接口通常希望客户端始终遍历数组，可以在响应组装处统一写成 items: make([]Item, 0)；如果“未查询”和“查询后无结果”有业务差别，则保留 nil 与空 slice 的区别，并在接口文档中明确说明。

让列表接口稳定返回 [] 的实用写法

最容易维护的方案是在边界层归一化，而不是在每个查询函数里猜客户端需求。数据库查询、缓存读取或过滤逻辑可以返回 nil；进入 HTTP 响应 DTO 时再转换为空 slice。

type UserList struct {
    Users []User `json:"users"`
}

func newUserList(users []User) UserList {
    if users == nil {
        // 已完成查询但没有记录时，接口契约要求返回 JSON 空数组。
        users = make([]User, 0)
    }
    return UserList{Users: users}
}

不要只在序列化前临时改值却忘记错误分支。成功的空结果、分页超出范围和过滤后为空，都应经过同一个 DTO 构造函数。若项目必须继续使用 omitempty，则不能同时要求客户端看到 "users":[]，因为标签的语义就是隐藏空值。

别忽略 encoding/json/v2 的迁移差异

当前官方文档把传统 encoding/json 说明为 v1，并列出了 encoding/json/v2 的差异：v1 的 nil slice 默认是 JSON null，v2 默认是空 JSON 数组。也就是说，文章或代码只写“Go nil slice 一定输出 null”已经不够严谨，必须连同导入路径和选项一起判断。旧项目继续用 v1 时，按上面的表处理；新代码采用 v2 时，检查是否显式启用了兼容 v1 的选项，并为接口做回归样例。

反序列化也有对应差异：在 v1 中，JSON null 写入 slice 会得到 nil；JSON 空数组会替换成新的空 slice。客户端如果需要区分字段缺失、null 和空数组，就不要只依赖 len，应设计明确的字段存在性或指针层级。

常见问题

nil slice 能不能直接 append？

可以。append 会按需分配底层数组；是否能 append 与 JSON 最终输出是两个问题。

空 slice 和 nil slice 的 len 一样吗？

通常都为 0，但可以用 s == nil 区分。只有 slice 类型才能与 nil 比较，不能拿它和空字面量比较。

怎样保证接口永远返回空数组？

在响应 DTO 边界把 nil slice 转成 make([]T, 0)，并去掉会省略该字段的 omitempty；同时为成功空结果和异常分支分别写响应样例。