Go 接口返回 null 而不是 []：nil slice 和空切片怎么选

一个订单列表接口在测试环境里看起来完全正常：查询没有报错，接口也返回了 200。可前端刚接入就发现 items.map(...) 走不下去，因为服务端给的是 {"items":null}，而页面约定的是数组。排查到最后往往不是数据库问题，而是 Go 里一个没有初始化的 slice 被传统 encoding/json 如实编码成了 null。

一次看似正常的列表查询，为什么会撞到 null

先还原这个问题出现的场景。一个后台列表页请求待处理订单，仓储层没有找到记录，于是返回了 nil slice 和 nil 错误；handler 随即把结果写入响应。对 Go 调用方而言，nil slice 的长度是 0，遍历它也安全，所以服务端本地逻辑没有异常。JSON 形状却把这个内部细节暴露给了调用方。

这里的判断不该由某个页面临时决定。若客户端协议把 items 定义为“总会出现的列表”，[] 能让 Web、移动端和其他服务都按同一种数据形状处理；若 null 特意表示“尚未计算”或“权限不足而未提供”，那就应该保留它。关键不是哪种写法更漂亮，而是字段含义能否稳定。

先用一段最小代码把 nil 和空切片钉住

在传统 encoding/json 中，二者的编码结果并不相同。下面这段代码只为观察返回形状，不依赖数据库或框架：

package main

import (
    "encoding/json"
    "fmt"
)

type Order struct {
    ID string `json:"id"`
}

type ListResponse struct {
    Items []Order `json:"items"`
}

func main() {
    nilValue := ListResponse{}
    emptyValue := ListResponse{Items: []Order{}}

    a, _ := json.Marshal(nilValue)
    b, _ := json.Marshal(emptyValue)

    fmt.Println(string(a)) // {"items":null}
    fmt.Println(string(b)) // {"items":[]}
}

两份结果在 Go 内存里都可以被当作“没有元素”处理，但 HTTP 响应是跨语言契约。JavaScript、Swift、Kotlin 或另一个 Go 服务都可能据此走不同分支。发现这一点后，不要急着在每个仓储方法里分配空 slice；先明确归一化应发生在哪一层。

把“总是数组”的约定放在响应边界

假设订单列表对调用方承诺：查询成功时 items 必然存在，没记录时就是空数组。仓储层可以保留它惯常的 nil 结果，handler 在确认没有错误后再归一化。这样不会把传输格式的偏好渗进所有查询实现。

func listOrders(w http.ResponseWriter, r *http.Request) {
    orders, err := repo.FindOrders(r.Context())
    if err != nil {
        http.Error(w, "query orders failed", http.StatusInternalServerError)
        return
    }

    if orders == nil {
        orders = []Order{}
    }

    w.Header().Set("Content-Type", "application/json")
    _ = json.NewEncoder(w).Encode(ListResponse{Items: orders})
}

这个位置有两个前提。第一，只有在 err == nil 时才做归一化，不能把查询失败伪装成空列表；第二，响应模型需要明确是对外模型，不要把数据库实体直接裸露给客户端。以后接口新增分页、权限状态或统计字段时，边界依旧清楚。

别把成功为空和未查询混在一起

有些场景中 nil 确实有业务含义。例如推荐模块尚未计算、异步任务未完成，或权限策略决定不返回某一段数据。这时 null、字段缺失与 [] 不能混成一个值。可以使用单独状态字段，或让响应模型用指针表达“是否提供”，同时在接口文档中说明三种形状各自代表什么。

为什么加上 omitempty 后，空数组又不见了

不少人修完 nil slice 后，顺手给字段加上 omitempty，结果测试又得到 {}。原因是传统 encoding/json 把长度为零的 slice 也视为可省略值；nil slice 和空切片都会让字段消失。若接口要稳定给出 items: []，这个标签正好与目标相反。

为接口写一条返回形状测试

这个问题最容易在重构时重新出现：有人把 []Order{} 改回零值，或者把标签补成 omitempty，编译和普通业务测试都可能仍然通过。针对对外 JSON 的小测试成本很低，却能把契约固定住。

func TestListResponseUsesEmptyArray(t *testing.T) {
    payload := ListResponse{Items: []Order{}}

    got, err := json.Marshal(payload)
    if err != nil {
        t.Fatal(err)
    }
    if string(got) != `{"items":[]}` {
        t.Fatalf("unexpected response: %s", got)
    }
}

如果接口已有 OpenAPI 描述、契约测试或前后端联调样例，也把这个预期同步进去。仅靠服务端代码约定很容易在多团队协作时丢失；让测试、示例和文档都出现同一个 JSON 形状，修改的人才会意识到它是兼容性变更。

升级到 encoding/json/v2 时再核对一次默认语义

Go 官方当前文档同时描述传统 encoding/json 与新的 encoding/json/v2：传统包会把 nil slice 编码成 null，而 v2 对 nil slice 和 map 的默认输出规则不同。不要只因为 import 路径看起来相近，就沿用旧项目里的序列化结论。涉及迁移时，最稳妥的做法是为关键响应保存一组 JSON 快照，并在升级分支上逐项比较。

这也解释了为什么“把所有 nil slice 都改成空切片”不是通用答案。先确认项目正在使用的编码包、选项与既有 API 承诺，再决定要维持历史形状还是主动发布一个可控的契约升级。

相关问题

nil slice 能安全遍历，为什么还要初始化？

在 Go 函数内部通常不需要初始化，因为 len、range 和 append 都能处理 nil slice。初始化的理由主要来自跨边界格式：当它要编码为 JSON 且接口要求数组形状时，才需要在合适的响应层处理。

能不能让仓储层永远返回空切片？

可以，但这会让存储实现承担传输契约。若团队已经把“查询无记录返回空切片”定为统一规范，也应配套测试。更重要的是不要用空切片覆盖错误；结果为空和查询失败仍要有清晰的不同路径。

只改前端的空值判断行不行？

前端做容错能防止页面崩溃，但并不能消除协议歧义。多个客户端会各自补一次判断，长期更难维护。优先稳定服务端对外字段形状，再把客户端容错当作额外保护。

关于传统包、omitempty 和 v2 默认行为的具体说明，可核对 Go 官方 encoding/json 文档。把 JSON 返回形状当作接口的一部分，列表接口就不会再因为一个零值让调用方临时猜测。