Go time.Time 序列化怎样固定时区和格式

Go 的 time.Time 直接交给 encoding/json 时，默认会输出带时区偏移的 RFC 3339 字符串。真正需要“固定时区和格式”时，推荐把规则放在接口边界：先用 In 转换到约定时区，再决定使用默认 RFC 3339，或用包装类型实现自定义格式。不要依赖部署机器的 Local 时区。

先记住三条：时区转换不改变时间瞬间；格式化只改变字符串表示；自定义 JSON 应只作用于需要该契约的字段。

先把 time.Time 转到明确的时区

time.LoadLocation 使用 IANA 时区名称，例如 Asia/Shanghai。它可能读取系统时区数据，因此适合在服务启动时加载一次并复用。Time.In 返回同一瞬间在目标位置的表示，不是给时间加上几个小时。

package main

import (
    "encoding/json"
    "fmt"
    "time"
)

func main() {
    // 生产环境应在启动阶段加载并缓存 Location，避免每次请求重复查找时区数据。
    shanghai, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        // 时区数据缺失时继续输出会造成接口契约漂移，因此直接终止启动。
        panic(err)
    }

    // Now 取得的是当前瞬间；In 只改变展示位置，不改变 Unix 时间点。
    occurredAt := time.Now().In(shanghai)
    body := struct {
        OccurredAt time.Time `json:"occurred_at"`
    }{OccurredAt: occurredAt}

    encoded, err := json.Marshal(body)
    if err != nil {
        // MarshalJSON 可能因时间超出 RFC3339 可表示范围而返回错误。
        panic(err)
    }
    fmt.Println(string(encoded))
}

默认结果类似 {"occurred_at":"2026-10-14T09:30:00.123456+08:00"}。标准库的 MarshalJSON 已实现 json.Marshaler，输出是带引号的 RFC 3339 字符串，并可能包含亚秒精度。只要所有服务都约定 UTC 或同一个业务时区，默认行为通常已经足够。

默认格式和自定义格式怎么选

跨服务、日志和事件消息优先使用 RFC 3339，尤其是 UTC：它保留偏移，便于排序和跨语言解析。如果前端或旧接口必须接收 2006-01-02 15:04:05，不要修改 time.Time 的全局行为，可以为单个字段定义别名类型。

type APITime time.Time

func (t APITime) MarshalJSON() ([]byte, error) {
    // 先把别名还原为 time.Time，再转换到接口约定的业务时区。
    local := time.Time(t).In(apiLocation)
    // 用 strconv.Quote 保证结果是合法 JSON 字符串，避免手工拼接转义错误。
    return []byte(strconv.Quote(local.Format("2006-01-02 15:04:05"))), nil
}

type Event struct {
    // 只有该接口需要旧格式，其他字段仍可使用标准 time.Time。
    OccurredAt APITime `json:"occurred_at"`
}

上例中的 apiLocation 应在初始化时获得，并在构造响应前确认不为 nil；完整实现需要同时导入 strconv，并根据项目结构注入时区。若还要接收同一格式，则为 *APITime 实现 UnmarshalJSON，调用 time.ParseInLocation，不要只改输出而忽略输入契约。

序列化边界与常见误区

第一，In 不等于加时差：同一时刻从 UTC 转到上海后，钟面会变化，但 Unix() 不变。第二，序列化保存的是偏移，不保存 IANA 时区名称；带夏令时的地区不能仅靠 +08:00 恢复原始规则。第三，time.Time.String() 更适合调试，稳定传输应使用 MarshalJSON、MarshalText 或显式 Format。

上线前的最小检查清单

把时区加载失败视为配置错误；在启动阶段固定 Location；为夏令时地区使用 IANA 名称而不是手写偏移；为零值时间约定是否输出 0001-01-01T00:00:00Z 或改用指针；为自定义格式补充 UnmarshalJSON 和跨语言样例。这样排查到的“时间差八小时”，通常能明确归因于展示时区、解析位置或接口格式，而不是靠改时间戳碰运气。

相关问题

为什么同一个时间在不同机器上输出不同？通常是代码使用了 Local 或在没有偏移的字符串上使用了本地解析。将传输格式统一为 RFC3339，并显式传入目标 Location。

固定格式后还能按时间排序吗？UTC 的 RFC3339 文本最稳妥；自定义格式若省略时区或精度，排序前应先解析回时间值，不能只比较展示字符串。