Go encoding/json omitempty 区分 nil 切片和空切片输出的处理方法

接口返回列表时，nil 切片、空切片和带 omitempty 的字段不是一回事：前两者通常分别编码为 null 和 []，加上 omitempty 后，空切片还可能直接让字段消失。稳定做法是先确定接口契约；如果下游始终按数组读取，就返回初始化过的空切片并去掉 omitempty，不要把序列化结果交给零值“碰运气”。

先把 nil、空切片和 omitempty 放进同一个复现

不要先改 Handler。把三个值放进同一段结构体，输出差异会非常直观：

package main

import (
    "encoding/json"
    "fmt"
)

type Response struct {
    // 不加 omitempty，字段始终参与编码。
    Items []string `json:"items"`
    // 空切片会被当作空值，可能直接省略字段。
    Optional []string `json:"optional,omitempty"`
}

func main() {
    // nil 切片代表尚未分配，不等同于空数组。
    var nilItems []string
    cases := []Response{
        {Items: nilItems, Optional: nilItems},
        {Items: []string{}, Optional: []string{}},
        {Items: []string{"go"}, Optional: []string{}},
    }
    for _, item := range cases {
        // 保留错误处理，避免把编码失败误当成空结果。
        data, err := json.Marshal(item)
        if err != nil {
            panic(err)
        }
        fmt.Println(string(data))
    }
}

这三行结果的关键差别是：

字段为什么会消失：omitempty 判断的是空值

omitempty 适合“字段没有意义时可以不传”的协议，但不适合所有列表接口。它会把空切片视为空值，所以即使你写的是 []string{}，序列化后也没有 optional 字段。这个行为与前端期待的“始终有一个数组”存在冲突。

排查时沿着三处看：结构体标签是否带 omitempty；组装响应时切片是否仍为 nil；调用方把缺失字段和 null 是否当作同一种状态。只改初始化，无法阻止 omitempty 删除字段。

列表接口的修复方案：固定字段形状

如果接口约定 items 永远是数组，推荐在边界处收敛零值，并移除 omitempty：

type ListResponse struct {
    // 用空数组表示“查询成功但没有数据”。
    Items []string `json:"items"`
}

func newListResponse(items []string) ListResponse {
    // 把内部 nil 统一转换为可预期的 JSON 数组。
    if items == nil {
        items = make([]string, 0)
    }
    return ListResponse{Items: items}
}

如果业务明确区分“未查询”“查询为空”和“没有权限”，则保留 null 或字段缺失也可以，但要把状态写进接口文档，而不是让不同代码路径偶然产生不同形状。

用回归测试锁住三种结果

最容易复发的是某个分支忘了初始化切片，或者有人为了缩短响应体重新加回 omitempty。用表驱动测试把协议写下来：

func TestListResponseJSON(t *testing.T) {
    tests := []struct {
        name string
        in   []string
        want string
    }{
        {name: "nil becomes empty array", in: nil, want: `{"items":[]}`},
        {name: "non-empty remains", in: []string{"go"}, want: `{"items":["go"]}`},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // 统一走响应构造函数，测试的正是接口边界。
            got, err := json.Marshal(newListResponse(tt.in))
            if err != nil {
                t.Fatal(err)
            }
            if string(got) != tt.want {
                t.Fatalf("got %s, want %s", got, tt.want)
            }
        })
    }
}

相关问题

nil 切片和空切片在 Go 中长度是否不同？

两者长度都为 0，但 nil 切片没有底层数组；JSON 编码时通常分别表现为 null 与 []。

只把 nil 初始化为空切片就够了吗？

如果标签仍有 omitempty，空切片仍可能被省略。要固定字段存在，需同时移除该标签。

什么时候应该保留 omitempty？

当字段缺失确实表达“未提供”且下游能区分缺失、null 与空数组时再使用，并用测试固定协议。