在 Go 中，使用 omitempty 标签时，uint64 等零值类型（如 0、""、false、nil）均被忽略；若需保留 0 作为有效值，应改用指针类型（如 *uint64），从而通过 nil 表示“未设置”，而 &0 明确表达“设为零”。
在 go 中，使用 `omitempty` 标签时，`uint64` 等零值类型（如 0、""、false、nil）均被忽略；若需保留 `0` 作为有效值，应改用指针类型（如 `*uint64`），从而通过 `nil` 表示“未设置”，而 `&0` 明确表达“设为零”。
Go 的 encoding/json 包在处理 omitempty 时，其判定逻辑基于零值（zero value）：只要字段值等于其类型的零值（例如 uint64 的零值是 0），该字段就会被省略。这导致一个常见痛点——业务上 offset: 0 可能具有明确语义（如“从首条记录开始分页”），但序列化后却完全消失，接收方无法区分“用户未传 offset”和“用户显式指定 offset=0”。
✅ 正确解法：使用指针类型实现三态语义
将字段声明为指针类型，可自然支持三种状态：
- nil → 字段未设置（omitempty 下不输出）
- &0 → 字段已设置且值为 0（正常输出 "offset": 0）
- &n（n≠0）→ 字段已设置且值非零（正常输出 "offset": n）
type Pagination struct {
Offset *uint64 `json:"offset,omitempty"`
Limit *uint64 `json:"limit,omitempty"`
}示例对比
// 情况1：全未设置
p1 := Pagination{}
data1, _ := json.Marshal(p1)
fmt.Println(string(data1)) // 输出：{}
// 情况2：仅设置 Offset = 0
p2 := Pagination{}
p2.Offset = new(uint64) // 等价于 p2.Offset = &uint64(0)
data2, _ := json.Marshal(p2)
fmt.Println(string(data2)) // 输出：{"offset":0}
// 情况3：Offset = 10
p3 := Pagination{}
val := uint64(10)
p3.Offset = &val
data3, _ := json.Marshal(p3)
fmt.Println(string(data3)) // 输出：{"offset":10}⚠️ 注意事项
-
解引用安全：访问指针字段前务必判空，避免 panic：
if p.Offset != nil { fmt.Printf("Offset is %d", *p.Offset) } - API 兼容性：若结构体用于 HTTP 请求/响应，前端需理解 null 表示“未提供”，而 0 表示“显式设为零”。
- 性能权衡：指针引入一次内存分配（new(T) 或 &v），对高频小对象场景需评估影响；但绝大多数 Web API 场景中可忽略。
- 替代方案（不推荐）：自定义 MarshalJSON 方法虽可行，但破坏结构体简洁性，增加维护成本，且易出错。
✅ 总结
*uint64（或 *int, *bool 等）是 Go 生态中处理“可选但需保留零值”语义的标准、惯用且最清晰的方案。它不依赖 magic number（如 -1 作无效标记），不侵入业务逻辑，完全契合 JSON 的 null 语义，并被主流框架（如 Gin、Echo、Swagger 生成器）原生支持。在定义 API 数据结构时，凡涉及“零值有意义”的数值字段，优先考虑指针类型。
