Go omitempty与指针字段组合表达JSON缺省值的设计要点

接口字段最容易出错的地方，不是 JSON 语法，而是“没有传”“主动传空”和“传了零值”是否被当成同一件事。Go 的 omitempty 适合减少无意义字段，但它不会替业务决定空值语义。比较稳妥的做法是：不需要区分时使用值字段加 omitempty；需要区分缺省与显式零值时使用指针字段，再让 nil 表示缺省、非 nil 指针表示一次明确输入。

官方文档：https://pkg.go.dev/encoding/json

先把四种字段状态分开

Go 规范规定，指针的零值是 nil。encoding/json 在编码时会把非 nil 指针编码成它指向的值，把 nil 指针编码成 null。因此，值字段和指针字段的“空”并不是同一个概念。

注意，omitempty 作用在编码阶段。一个没有 omitempty 的 nil 指针会输出 null；加上它以后，nil 指针会直接消失。对于值字段，空字符串、数字 0 和 false 也会被当作 empty。这个规则决定了字段声明本身就是接口契约的一部分。

用指针保留有意义的零值

下面这个请求结构适合“可选更新”场景。辅助函数只负责把普通字面量变成指针，真正重要的是字段类型与 tag 的组合。

package main

import (
    "encoding/json"
    "fmt"
)

// ProfilePatch 用 nil 表示本次请求没有修改该字段。
type ProfilePatch struct {
    DisplayName *string `json:"display_name,omitempty"`
    Age         *int    `json:"age,omitempty"`
    Enabled     *bool   `json:"enabled,omitempty"`
    // 备注为空时没有业务意义，所以使用值字段即可。
    Note string `json:"note,omitempty"`
}

// ptr 把明确传入的零值也保留下来，避免与“未传”混淆。
func ptr[T any](v T) *T { return &v }

func main() {
    p := ProfilePatch{
        DisplayName: ptr(""),  // 主动清空，JSON 仍保留空串。
        Age:         ptr(0),   // 明确把年龄改成 0，不能被省略。
        Enabled:     ptr(false), // 明确关闭开关，不能被省略。
    }
    data, err := json.Marshal(p)
    if err != nil {
        // 发布请求前保留错误，避免把不完整 JSON 发到接口。
        panic(err)
    }
    fmt.Println(string(data))
}

这段结构的关键不是“所有字段都改成指针”。如果 Note 的空串没有业务含义，继续用值字段更简单；如果 Enabled 的 false 表示一次明确操作，就应该用 *bool。指针的成本是调用方需要处理 nil、构造代码更长，并且读取字段时要先判断存在性。

PATCH 请求应该优先表达业务语义

在 PATCH 语义里，常见的三种动作可以直接映射到指针状态：nil 表示保留旧值，指向空串表示清空，指向具体值表示更新。这样服务端不必猜测一个空字符串到底是用户输入，还是客户端默认值。

// applyPatch 只对本次请求明确出现的字段执行更新。
func applyPatch(user *User, p ProfilePatch) {
    if p.DisplayName != nil {
        // 非 nil 代表明确更新，空串也要照常写入。
        user.DisplayName = *p.DisplayName
    }
    if p.Age != nil {
        // 0 是有效输入时，不能用 if *p.Age != 0 判断。
        user.Age = *p.Age
    }
    if p.Enabled != nil {
        // false 是关闭动作，必须通过指针存在性判断。
        user.Enabled = *p.Enabled
    }
}

type User struct {
    DisplayName string
    Age         int
    Enabled     bool
}

这里还有一个容易被忽略的边界：把 JSON 解码到 *string 时，字段缺失和字段值为 null 都可能表现为 nil。若接口必须区分“没有修改”与“主动设置 null”，仅靠一层指针不够，需要使用显式存在位、三态类型或自定义解码器记录字段是否出现。

上线前检查字段契约

可以用下面的清单逐个检查请求和响应结构：

• 空字符串、0、false 是否是有意义的主动输入？是，就优先考虑指针字段。
• nil 在当前接口中代表“缺省”、还是必须输出为 JSON null？前者加 omitempty，后者不要加。
• 这是 PATCH 更新对象还是完整响应对象？更新对象更需要存在性；完整响应通常更偏向稳定输出。
• 服务端是否需要区分 JSON 缺失与 JSON null？需要时提前设计三态，而不是上线后依赖猜测。

最终选择可以压缩成一句话：值字段表达“空值没有意义”，指针字段表达“有没有传本身有意义”，omitempty 只负责把已经确定无意义的状态从 JSON 中省略。

相关问题

omitempty 会把指向 0 的 *int 省略吗？

不会。只要指针不是 nil，传统编码规则会编码它指向的 0；被省略的是 nil 指针。

为什么值字段无法表达“未传”和“传了 false”？

值字段总有一个默认零值，解码后两种输入都可能得到 false。用 *bool 才能用 nil 表示未提供，用非 nil 表示明确输入。

字段不加 omitempty 就能区分缺失和 null 吗？

不一定。它只影响编码；解码时缺失字段不会写入，而 null 可能把指针置为 nil。若两者必须区分，需要额外的存在性记录。