Go time.Time JSON 格式和自定义格式怎么共存
来源:17golang原创
时间:2026-11-16 11:23:08 473浏览 收藏
在 Go 服务里,time.Time 默认会通过自己的 MarshalJSON 输出带引号的 RFC3339 时间字符串;如果只有某几个业务字段要求 2006/01/02 15:04:05 这类格式,不要改写 time.Time 的全局行为。更稳妥的做法是保留普通字段为 time.Time,再为特殊字段定义一个包装类型,同时实现 MarshalJSON 和 UnmarshalJSON。
这样做的结果是:标准字段继续兼容 RFC3339,旧接口或展示字段拥有自己的字符串格式,输入端再统一到 UTC。下面按一个 API 同时承载两种时间契约的场景拆开说明。
先把业务负载和时间契约分开
假设订单响应里有两个字段:created_at 是服务间传输的事件时刻,希望使用标准 RFC3339;display_date 是历史页面依赖的业务日期,需要输出固定的年月日和时分秒。它们都表示时间,却不是同一份 JSON 契约。
| 字段类型 | 默认输出 | 适用场景 | 维护方式 |
|---|---|---|---|
time.Time | 带引号的 RFC3339 字符串 | 服务间 API、事件、审计时间 | 直接使用标准库方法 |
CustomTime | 约定的业务格式 | 兼容旧页面、固定报表字段 | 在包装类型上成对实现 JSON 方法 |
官方文档说明,time.Time.MarshalJSON 输出 RFC3339 格式的带引号字符串,UnmarshalJSON 则要求输入是 RFC3339 格式的带引号字符串。自定义格式属于应用层契约,应该由应用层类型承担。
用包装类型承接自定义 JSON 格式
先定义固定 layout,再把 time.Time 嵌入 CustomTime。嵌入让业务代码仍然可以使用时间值的方法;JSON 行为则由包装类型自己的方法接管。
package main
import (
"encoding/json"
"fmt"
"time"
)
// CustomTime 只给需要旧格式的字段使用,不改变 time.Time 的默认 JSON 行为。
type CustomTime struct {
time.Time
}
const customLayout = "2006/01/02 15:04:05"
// MarshalJSON 把业务字段格式化为固定字符串;json.Marshal 负责正确加引号。
func (t CustomTime) MarshalJSON() ([]byte, error) {
return json.Marshal(t.Time.UTC().Format(customLayout))
}
// UnmarshalJSON 先按 JSON 字符串解包,再按同一个 layout 解析并归一化到 UTC。
func (t *CustomTime) UnmarshalJSON(data []byte) error {
var value string
if err := json.Unmarshal(data, &value); err != nil {
return fmt.Errorf("custom time must be a JSON string: %w", err)
}
parsed, err := time.ParseInLocation(customLayout, value, time.UTC)
if err != nil {
return fmt.Errorf("parse custom time %q: %w", value, err)
}
t.Time = parsed.UTC()
return nil
}
这里最重要的是不要手写带引号的 JSON。直接拼接字符串容易遇到转义问题,交给 json.Marshal 更安全。UnmarshalJSON 使用指针接收者,因为它需要把解析后的值写回当前字段。

让默认字段和自定义字段在同一个结构体里共存
包装类型的价值在于作用域清楚:只有声明为 CustomTime 的字段采用自定义格式,普通 time.Time 字段仍按标准库规则工作。
type OrderView struct {
// CreatedAt 面向服务间通信,保留 RFC3339 和时区偏移信息。
CreatedAt time.Time `json:"created_at"`
// DisplayDate 面向历史页面,固定使用业务约定的日期格式。
DisplayDate CustomTime `json:"display_date"`
}
func main() {
// 用同一个瞬间构造两种字段,便于观察 JSON 契约差异。
instant := time.Date(2026, 11, 16, 9, 30, 0, 0, time.FixedZone("CST", 8*60*60))
payload, err := json.Marshal(OrderView{
CreatedAt: instant,
DisplayDate: CustomTime{Time: instant},
})
if err != nil {
panic(err) // 示例直接终止;生产代码应把错误交给 HTTP 层。
}
fmt.Println(string(payload))
}
输出的具体时区表达由值本身决定,但字段职责不会混淆:created_at 仍由 time.Time.MarshalJSON 负责,display_date 则由 CustomTime.MarshalJSON 负责。不要为了让两个字段看起来一样而把所有时间都强制转换成展示字符串。
输入端要和输出端使用同一份契约
只重写 MarshalJSON 而不重写 UnmarshalJSON,会出现“能发不能收”的单向格式。自定义字段应当把输出 layout 和输入解析 layout 绑定在一起,并在解析完成后明确时区策略。
func decodeOrder(data []byte) (OrderView, error) {
var order OrderView
// Decode 会调用 CustomTime.UnmarshalJSON,格式错误会直接返回。
if err := json.Unmarshal(data, &order); err != nil {
return OrderView{}, err
}
// 标准字段也统一到 UTC,便于后续比较、排序和持久化。
order.CreatedAt = order.CreatedAt.UTC()
return order, nil
}
这段代码把“解析成功”和“时区统一”分成两个明确动作。CustomTime 自己在 UnmarshalJSON 内完成 UTC 归一化;普通字段在结构体解码后调用 UTC()。如果项目决定保留原始偏移量,则应删除对应的归一化动作,并把这个选择写进接口契约。

UTC 选择要看业务负载,而不是看显示习惯
UTC 适合事件时刻、过期时间、排序字段和跨服务数据。它表达的是统一的瞬间;用户所在时区属于展示层,通常应该在渲染时再转换。
对于不带时区的自定义字符串,例如 2026/11/16 09:30:00,示例使用 time.ParseInLocation(..., time.UTC),表示“这串文本按 UTC 解释”。如果这串文本实际上代表业务所在地时间,就应该传入明确的业务 location,不能因为服务器运行在 UTC 就默认它是 UTC。
func parseBusinessTime(value string, loc *time.Location) (time.Time, error) {
// 无时区文本必须由调用方提供解释它的 location,避免静默错位。
parsed, err := time.ParseInLocation(customLayout, value, loc)
if err != nil {
return time.Time{}, fmt.Errorf("parse business time: %w", err)
}
// 存储和比较前统一为 UTC,展示时再转回用户时区。
return parsed.UTC(), nil
}
带有 +08:00 或 Z 的输入则包含时区信息,不能再把它当作无时区文本处理。关键不是“所有字符串都调用 UTC”,而是先确认文本的时区语义,再统一内部时间值。
方案取舍:默认字段、包装类型还是字符串
| 方案 | 优点 | 代价 | 推荐条件 |
|---|---|---|---|
直接使用 time.Time | 标准库行为明确,跨服务兼容性好 | 不能满足固定旧格式 | 新接口、事件流、内部服务 |
| 包装类型实现 JSON 方法 | 格式作用域小,输入输出可对称控制 | 需要维护 layout 和错误策略 | 单个字段需要兼容历史契约 |
到处使用 string | 表面上最灵活 | 丢失时间语义,比较和校验分散 | 只在边界层临时接收未知格式 |
在一个同时连接多个系统的服务里,包装类型通常是成本和兼容性之间的平衡点:领域代码仍然拿到 time.Time,JSON 契约只在字段边界发生变化。
上线前检查这 6 个边界
- 默认 RFC3339 字段是否仍声明为
time.Time,没有被全局替换成字符串。 - 自定义字段是否同时实现
MarshalJSON与UnmarshalJSON。 - layout 是否集中定义,输入和输出是否使用同一个规则。
- 无时区字符串由哪个 location 解释,是否明确写在接口文档中。
- 内部比较和持久化是否统一使用 UTC,展示转换是否留在展示层。
- 空字符串、
null、字段缺失和非法日期是否有明确的错误或零值策略。
常见问题
为什么不直接给 time.Time 写一个全局自定义格式?
time.Time 是标准库类型,修改它的行为既不可行,也会让不需要自定义格式的接口失去 RFC3339 兼容性。用包装类型把变化限制到具体字段更容易演进。
CustomTime 嵌入 time.Time 后,Format 还能直接调用吗?
可以。嵌入字段会提升其方法,业务代码仍可以调用 value.Format(layout)、value.UTC() 等方法;但 JSON 序列化行为由包装类型显式实现的方法决定。
为什么 ParseInLocation 不能随便换成 Parse?
没有时区信息的文本必须有一个解释它的 location。Parse 对无时区输入采用 UTC,而 ParseInLocation 允许你把业务所在地作为契约的一部分传入,二者表达的业务含义不同。
最终建议很简单:把标准时间和业务展示时间当成两种负载,默认字段继续使用 time.Time,特殊字段使用小而明确的包装类型;在输入边界决定 location,在内部统一 UTC,在输出边界再决定 JSON 格式。
-
502 收藏
-
502 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
464 收藏
-
473 收藏
-
394 收藏
-
445 收藏
-
146 收藏
-
462 收藏
-
316 收藏
-
168 收藏
-
404 收藏
-
425 收藏
-
127 收藏
-
366 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习