Go API返回空集合时统一nil slice和[]的响应策略

列表接口最容易出现一个看似细小、实际会影响客户端分支的差异：Go 中没有结果时，slice 可能是 nil，也可能是长度为 0 的非 nil slice。使用传统 encoding/json 时，前者默认编码为 null，后者编码为 []。如果接口契约约定“列表永远是数组”，就应在响应边界统一初始化，而不是让客户端同时兼容两种形状。

先固定合同：nil slice 和空 slice 不是同一种 JSON

这两个 slice 都可以安全地执行 len、range 和 append，但序列化结果不同。下面的 response 类型没有任何业务差异，差异只来自字段的初始化状态：

package main

import (
    "encoding/json"
    "fmt"
)

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

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

func main() {
    // nil slice 在 encoding/json v1 中会输出 null。
    nilResult, _ := json.Marshal(ListResponse{Items: nil})

    // 非 nil 但长度为 0 的 slice 会输出 []，适合列表接口契约。
    emptyResult, _ := json.Marshal(ListResponse{Items: make([]Item, 0)})

    fmt.Println(string(nilResult))   // {"items":null}
    fmt.Println(string(emptyResult)) // {"items":[]}
}

因此，前端的 items.map(...)、类型校验器或 OpenAPI 客户端生成代码，可能会把 null 视为另一种状态。若“没有结果”与“字段不存在”没有业务区别，推荐把列表字段稳定成 []。

在 API 响应边界做一次归一化

不必强迫每个 repository 或查询函数都返回非 nil slice。查询层保持自然的零值返回，真正出网前集中处理更容易审计，也不会把 HTTP 契约细节渗透到数据访问层。

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

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

func newUserListResponse(users []User) UserListResponse {
    // 只在响应边界补齐空 slice，避免客户端收到 null。
    if users == nil {
        users = make([]User, 0)
    }
    return UserListResponse{Users: users}
}

func handleUsers(users []User) ([]byte, error) {
    // 统一构造 response，后续字段新增时仍只有一个出口。
    response := newUserListResponse(users)
    return json.Marshal(response)
}

工程上可以把这个构造函数放在 handler、presenter 或 transport 层。要注意错误响应不要混入成功列表字段；例如数据库超时应返回明确的错误对象，而不是用空数组掩盖失败。

迁移 encoding/json v1 与 v2 时先看客户端合同

当前官方文档把 encoding/json 称为 v1，并说明 v2 对 nil slice 的默认编码是空数组，而 v1 默认编码是 JSON null。这意味着升级 JSON 实现可能改变已有响应，即使 Go 结构体没有改动。不要把“新默认值更符合预期”直接当作兼容性证明。

迁移前可以先列出接口字段的外部约定，再决定是保留旧语义，还是让所有客户端接受新语义：

• 如果旧客户端把 null 当作“未加载”，列表接口继续显式保持 v1 语义，避免误触发空状态。
• 如果产品约定列表永远是数组，响应层归一化和 JSON 契约测试都应写成 []，迁移后继续验证。
• 如果使用 omitempty，要单独确认空 slice 是否应该被省略；“不出现”和“出现空数组”不是一回事。

用三组测试防止接口形状回退

测试不只覆盖有数据的 happy path，还要把零结果、正常结果和错误结果分别断言。直接断言 JSON 片段比只断言 slice 长度更接近客户端真正看到的合同：

func TestUserListResponseEmptyArray(t *testing.T) {
    // 断言出网 JSON，而不是只检查 Go slice 的 len。
    body, err := json.Marshal(newUserListResponse(nil))
    if err != nil {
        t.Fatal(err)
    }
    want := `{"users":[]}`
    if string(body) != want {
        t.Fatalf("响应形状错误：got %s want %s", body, want)
    }
}

生产代码中若字段很多，可以把契约测试放在 handler 或序列化适配层；只要能捕获 null 与 [] 的变化即可。对嵌套列表也要同样处理，不要只修顶层字段。

常见问题

把 nil slice 改成空 slice 会影响 append 吗？

不会。两者都能 append，主要差异在序列化和显式的 nil 判断；修改前仍应确认业务是否把 nil 当作“未加载”。

omitempty 能保证返回空数组吗？

不能。它的目标是省略空值字段，往往会让字段消失，而不是生成 []。要稳定返回数组，应先归一化并使用不带 omitempty 的字段标签。

只在前端把 null 转成 [] 可以吗？

可以作为兼容层，但会把同一接口的语义分散到多个客户端。能控制 Go API 时，在服务边界统一通常更容易测试、记录和迁移。

空集合策略的关键不是偏好 null 还是 []，而是把选择写进响应构造和契约测试。这样无论查询实现、客户端数量还是 JSON 库版本如何变化，接口的外部形状都不会靠零值碰运气。