登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go问答

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 使用指针接收者,因为它需要把解析后的值写回当前字段。

Go time.Time 默认 JSON 和自定义包装类型的静态关系说明图
图1:默认 RFC3339 契约与指定字段自定义格式的结构说明图,不是截图或运行证据。

让默认字段和自定义字段在同一个结构体里共存

包装类型的价值在于作用域清楚:只有声明为 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()。如果项目决定保留原始偏移量,则应删除对应的归一化动作,并把这个选择写进接口契约。

Go JSON 时间输入经过 UnmarshalJSON 解析并统一到 UTC 的结构说明图
图2:JSON 输入、解析、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 格式。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>