Go JSON 里的 omitempty 为什么漏不掉 time.Time？omitzero 和指针怎么选

Go 接口返回 JSON 时，很多人会给 time.Time 字段加上 omitempty，希望没有时间值就不输出字段，但结果里仍然出现 0001-01-01T00:00:00Z。这不是 JSON 包失效，而是 time.Time 属于结构体类型，旧的 omitempty 判断规则并不等同于 time.Time.IsZero()。如果项目已经使用 Go 1.24 及以上，优先考虑 omitzero；如果接口需要表达“这个时间没有设置”，用 *time.Time 通常更清楚；如果对外字段格式要长期稳定，单独定义 DTO 会更稳。

现象：omitempty 后仍输出 0001 时间

先看一个很常见的接口模型。字段明明写了 omitempty，但没有赋值的时间仍然会出现在 JSON 结果里。

type User struct {
    ID        int       `json:"id"`
    CreatedAt time.Time `json:"created_at,omitempty"`
}

当 CreatedAt 是 time.Time{} 时，很多开发者期待输出只有 id。实际容易看到类似结果：

{
  "id": 1001,
  "created_at": "0001-01-01T00:00:00Z"
}

这个时间不是业务里真实创建时间，而是 Go 的时间零值被编码成了字符串。问题的关键在于：omitempty 的“empty”不是你脑子里的“没有业务值”，它按 JSON 包定义的空值规则处理。对 time.Time 这种结构体字段，旧写法经常不能达到省略字段的目的。

数据流：time.Time 从结构体字段到 JSON 的路径

把这个问题放进数据生命周期里看，会更容易判断该改哪一层。请求或数据库读出来的数据先进入结构体字段，随后经过 JSON 标签规则，再进入响应体。omitempty 只是在编码阶段判断字段是否为空，它不会替你理解业务里的“未设置时间”。

如果字段来自数据库，生命周期还会多一层：数据库里的 NULL、Go 里的 time.Time{}、JSON 里的空字段或字符串，并不是同一个概念。把它们混在一个字段里，接口很快就会出现“后端觉得没值，前端却收到了 0001 时间”的错位。

新写法：Go 1.24+ 用 omitzero 省略零值

Go 1.24 的 encoding/json 文档加入了 omitzero 标签选项。它的语义更贴近 Go 类型的零值判断：如果类型有 IsZero() bool 方法，就按这个方法判断；否则按该类型的零值判断。对 time.Time 来说，这正好能覆盖 time.Time{} 这种场景。

type User struct {
    ID        int       `json:"id"`
    CreatedAt time.Time `json:"created_at,omitzero"`
}

使用这个写法后，零值时间更符合“没有业务时间就不输出字段”的直觉。它特别适合内部服务、Go 版本可控的新项目，以及你已经确认客户端能接受字段缺失的 API。

需要注意的是，omitzero 是更清晰的标签语义，但它不是接口兼容性的万能开关。如果一个线上接口过去一直返回 created_at，突然把零值时的字段去掉，老客户端可能会受到影响。技术上能省略，不代表业务上可以马上省略。

选择边界：omitzero、*time.Time 和 DTO 怎么选

真正写接口时，不要只问“哪个标签能省字段”，还要问字段背后的状态有几种。时间字段常见状态至少有三类：没有设置、已经设置、设置失败或需要展示默认值。字段类型和 JSON 标签要能表达这些状态。

如果你想让字段缺失时完全不出现在 JSON 里，指针是最直观的建模方式：

type User struct {
    ID        int        `json:"id"`
    CreatedAt *time.Time `json:"created_at,omitempty"`
}

当 CreatedAt 是 nil，字段会被省略；当它指向一个时间值，字段会正常输出。这个写法在数据库可空字段、可选审核时间、可选删除时间、可选首次登录时间里都很常见。

如果接口需要统一输出字符串、时间戳或本地时区格式，DTO 更适合承接对外契约：

type UserDTO struct {
    ID        int    `json:"id"`
    CreatedAt string `json:"created_at,omitempty"`
}

DTO 的优势是隔离内部模型和外部响应。数据库模型可以继续使用 time.Time 或可空时间类型，对外响应则按产品约定输出字符串、空字段或友好文案。

兼容处理：老版本和老客户端要怎么迁移

如果项目还不能升级到 Go 1.24，可以先用 *time.Time 或 DTO 解决对外输出问题。不要为了省一个字段，贸然修改数据库模型或公共结构体，否则可能牵动查询、缓存、文档和客户端解析。

更稳的迁移顺序可以这样安排：

• 先统计哪些接口会返回 0001-01-01T00:00:00Z，确认它是不是业务可见问题。
• 再查看客户端是否依赖这个字段一直存在，尤其是小程序、移动端和第三方调用方。
• 新接口优先使用 omitzero 或 *time.Time，老接口通过版本号、DTO 或文档说明渐进调整。
• 上线前补一组 JSON 快照测试，覆盖零值时间、有值时间、字段缺失三种状态。

很多线上问题不是 Go 标签本身造成的，而是字段语义没有提前写清楚。比如 deleted_at 是空字段表示“未删除”，还是返回 null 表示“未删除”，这应该由接口契约决定，而不是由某个标签偶然决定。

常见问题

omitempty 和 omitzero 可以一起写吗？

可以。组合写法会在“空值”或“零值”任一条件满足时省略字段。对大多数 time.Time 场景，单独使用 omitzero 已经足够清楚；如果字段类型还有空字符串、空切片等语义，再考虑组合。

所有时间字段都应该改成指针吗？

不需要。字段是否用指针，要看业务里有没有“未设置”这个状态。创建时间、更新时间这类必然存在的字段，用 time.Time 更自然；删除时间、审核时间、首次登录时间这类可选字段，用 *time.Time 更容易表达。

老项目能直接把 time.Time 改成 *time.Time 吗？

不建议直接大范围替换。类型变化会影响赋值、比较、数据库扫描、缓存反序列化和单元测试。更稳的方式是在对外 DTO 层先改输出，再决定内部模型是否需要调整。

为什么不让前端过滤 0001 时间？

前端可以兜底，但不应该承担主要语义。API 返回 0001-01-01T00:00:00Z 会让不同客户端各自猜测含义，长期看更容易出现展示不一致。后端把字段语义建模清楚，接口会更稳定。

总结

omitempty 省不掉 time.Time{}，本质上是字段语义和 JSON 标签规则没有对齐。新项目可以用 omitzero 处理零值省略；需要表达缺失状态时，用 *time.Time 更清楚；公开 API 和历史接口则优先用 DTO 稳住对外契约。判断标准很简单：先看字段有没有“未设置”状态，再看客户端能不能接受字段缺失，最后才决定标签怎么写。