Go nil slice 为什么 JSON 是 null：接口数组字段统一成 [] 的迁移清单

很多 Go 接口一开始返回的是 null，后来前端或调用方要求统一返回空数组 []。问题通常落在一个高频细节上：nil slice 和空 slice 在 Go 里都能正常遍历，但被 encoding/json 编码时结果不同。

直接回答：var s []int 是 nil slice，JSON 输出是 null；s := []int{} 是空 slice，JSON 输出是 []。如果接口契约要求数组字段始终是数组，就要把相关字段初始化为空 slice，并补上回归检查。

升级范围：把接口里的 null 数组统一成 []

这次讨论的不是 Go 语法升级，而是接口响应契约的迁移：把原来可能返回 null 的数组字段，统一迁移为 []。常见字段包括商品列表、订单明细、权限集合、搜索结果和错误明细。

先看一个最小例子：

package main

import (
    "encoding/json"
    "fmt"
)

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

func main() {
    var a []string
    b := []string{}

    one, _ := json.Marshal(Result{Items: a})
    two, _ := json.Marshal(Result{Items: b})

    fmt.Println(string(one)) // {"items":null}
    fmt.Println(string(two)) // {"items":[]}
}

这段输出就是迁移的核心原因：业务含义都可能是“没有数据”，但 JSON 结构对调用方并不一样。

变更表：nil slice 和空 slice 到底差在哪

nil slice 没有底层数组；空 slice 长度为 0，但已经是一个非 nil 的切片值。两者都可以 len，都可以 range，也都可以继续 append。差异主要出现在需要表达结构的场景里，尤其是 JSON 响应。

旧代码风险：调用方为什么会被 null 绊住

服务端看起来只是少初始化了一行，但调用方拿到的是两种 JSON 类型。风险主要有三类：

• 前端渲染：页面直接调用 items.map(...) 时，null 会导致运行时错误。
• 客户端模型：强类型客户端可能把数组字段定义为必填列表，遇到 null 需要额外分支。
• 接口契约：同一个字段有时是数组、有时是 null，会增加文档和测试成本。

如果接口文档写的是“数组”，实践中最好让空结果也保持数组结构。这样调用方可以把“没有数据”和“字段不存在”区分开。

新写法：初始化为空 slice 再返回

最直接的修复方式是在构造响应时初始化字段：

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

func BuildUserList(users []User) UserListResp {
    if users == nil {
        users = []User{}
    }
    return UserListResp{Users: users}
}

如果结构体里有多个数组字段，可以在响应构造函数里统一兜底：

type SearchResp struct {
    Products []Product `json:"products"`
    Filters  []Filter  `json:"filters"`
}

func NewSearchResp() SearchResp {
    return SearchResp{
        Products: []Product{},
        Filters:  []Filter{},
    }
}

注意不要把这个规则散落在很多控制器里。更稳妥的做法是让响应构造函数负责默认值，业务查询层只关心数据来源。

回归检查：JSON、单测和兼容边界

迁移不是把代码改完就结束。需要确认旧字段、新字段和空结果路径都符合预期：

func TestEmptyUsersShouldBeArray(t *testing.T) {
    resp := BuildUserList(nil)
    data, err := json.Marshal(resp)
    if err != nil {
        t.Fatal(err)
    }

    got := string(data)
    want := `{"users":[]}`
    if got != want {
        t.Fatalf("want %s, got %s", want, got)
    }
}

还要确认是否有调用方依赖 null 表示“未查询”。如果有，就不要静默改变语义，应该把字段拆开，例如增加 queried 状态字段，或者在接口版本里说明变更。

迁移清单：哪些位置需要一起改

最后给一份迁移清单，适合在接口评审或发布前逐项检查：

• 确认接口文档里数组字段是否声明为始终返回数组。
• 检查响应结构体里的 slice 字段是否有统一构造入口。
• 为 nil 输入补一条 JSON 输出单测。
• 检查分页空列表、筛选无结果、权限为空等典型路径。
• 和前端或客户端确认 null 到 [] 是否属于兼容变更。
• 发布后抽查真实响应，确认字段类型稳定。

总结一下：Go 的 nil slice 和空 slice 在普通遍历里差别不大，但在 JSON 接口里差别很明显。接口数组字段如果要表达“没有元素”，优先返回 []；如果要表达“没有查询或未知”，就显式增加状态字段，不要把两种语义混在一个 null 里。