Go time.Time 怎样明确 JSON 时区语义

Go 接口里的时间字段出现“少了 8 小时”或“回传后时区不见了”，通常不是 time.Time 把时间算错，而是协议没有说清楚：这个字段代表一个绝对瞬时点，还是某个地区的本地日历时间。推荐的默认约定是 JSON 使用带明确偏移的 RFC 3339 字符串，服务内部统一比较瞬时点；只有确实需要保留地区规则时，才额外传 IANA 时区名。

官方资料：https://pkg.go.dev/time

例如同一个瞬时点可以写成 2026-10-21T12:00:00Z，也可以写成 2026-10-21T20:00:00+08:00。两者的时刻相同，但只靠一个字符串不能推回原来使用的 Asia/Shanghai 这个 Location 名称。

先把时间的三层语义拆开

time.Time 同时携带墙上时间、时区位置和可选的单调时钟信息。调用 UTC()、Local() 或 In(loc) 会改变解释它的 Location，不会改变实际瞬时点；调用 Equal 比较的是瞬时点，而不是两个值的显示写法。

默认的 MarshalJSON 输出带引号的 RFC 3339 字符串，保留时区偏移；UnmarshalJSON 也要求输入是 RFC 3339 格式的字符串。序列化格式不会保留 IANA Location 名称，所以不要把反序列化后的 Location().String() 当成原始地区名来做业务判断。

如果接口只表达事件发生的时刻，统一输出 UTC 最容易维护：

type Event struct {
	CreatedAt time.Time `json:"created_at"`
}

func newEvent() Event {
	// 统一存储和传输瞬时点，避免依赖部署机器的 Local 时区。
	return Event{CreatedAt: time.Now().UTC()}
}

func exampleJSON() ([]byte, error) {
	// time.Time 会按 RFC3339 形式编码，调用方按偏移解析即可。
	return json.Marshal(newEvent())
}

如果产品需要让用户看到本地时间，可以在展示层把这个瞬时点转换到用户选择的 Location，而不是让后端根据进程的 time.Local 猜测。

用 UTC 或明确偏移生成稳定 JSON

生成时间时，关键不是把字符串手工拼成“看起来像北京时间”，而是先构造正确的 Location，再让 time.Time 负责格式化。固定偏移适合协议中已经确定的偏移；涉及夏令时或地区历史规则时，应使用 IANA 名称。

func makeBeijingTime() (time.Time, error) {
	loc, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		// 时区数据库不可用时不要静默改用服务器 Local。
		return time.Time{}, fmt.Errorf("load timezone: %w", err)
	}
	// 用地区规则构造本地时间，再由 MarshalJSON 输出带偏移的值。
	return time.Date(2026, 10, 21, 20, 0, 0, 0, loc), nil
}

type Meeting struct {
	StartsAt time.Time `json:"starts_at"`
}

func marshalMeeting() ([]byte, error) {
	t, err := makeBeijingTime()
	if err != nil {
		return nil, err
	}
	// 接口只需要瞬时点时，转 UTC 可让响应格式保持一致。
	return json.Marshal(Meeting{StartsAt: t.UTC()})
}

接口文档应明确三件事：字段是 RFC 3339 字符串；是否要求必须带 Z；客户端展示时是否允许转换到自己的时区。这样“同一时刻的不同偏移写法”就不会被误判成不同业务时间。

无时区输入要显式指定解释位置

有些表单会提交 2026-10-21 20:00:00，它没有偏移量，单独看无法判断是上海、东京还是 UTC。此时 time.Parse 会按 UTC 解释无时区输入；如果业务已经知道这是某个地区的本地时间，应先用 LoadLocation，再使用 ParseInLocation。

func parseLocalInput(value string) (time.Time, error) {
	loc, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		return time.Time{}, fmt.Errorf("load timezone: %w", err)
	}
	// 输入没有偏移时，明确声明它属于哪个地区的本地时间。
	return time.ParseInLocation("2006-01-02 15:04:05", value, loc)
}

不要通过修改服务器的 TZ 或 time.Local 来修复单个接口，这会把部署环境配置偷偷变成协议的一部分。带偏移的输入则应使用 time.Parse，让输入自身携带语义，不要再强行套一个 Location。

需要地区规则时，把 instant 和 zone 分开

日历预约、门店营业时间或周期任务常常同时需要“发生在哪个瞬时点”和“按哪个地区规则展示”。一个只含 time.Time 的字段无法完整保存后者，比较清楚的协议是拆成两个字段：

type ZonedEvent struct {
	Instant time.Time `json:"instant"`
	Zone    string    `json:"zone"`
}

func newZonedEvent(t time.Time, zone string) (ZonedEvent, error) {
	if _, err := time.LoadLocation(zone); err != nil {
		// 只接受 IANA 时区名，避免把任意缩写当成地区规则。
		return ZonedEvent{}, fmt.Errorf("invalid zone %q: %w", zone, err)
	}
	// instant 传输统一使用 UTC，zone 单独保留展示所需的地区标识。
	return ZonedEvent{Instant: t.UTC(), Zone: zone}, nil
}

读取时先解析 instant，再用 LoadLocation(Zone) 得到展示位置。若要把某个瞬时点显示到该地区，可调用 t.In(loc)；若要比较两个事件，使用 Equal、Before 或 After，不要用 == 代替业务时间比较。

还要约定零值策略。time.Time{} 是公元 1 年的零时间，不等于 JSON 的 null 业务语义；可选字段可以使用指针或明确的 nullable 类型。跨数据库保存时也要确认驱动是否把偏移、精度和零值按相同规则往返。

常见问题

JSON 里带了 +08:00，能恢复成 Asia/Shanghai 吗？

不能保证。偏移量只说明当时相对 UTC 的差值，不能唯一确定地区名称和历史规则。需要地区身份时单独传 zone。

为什么同一时刻的两个 time.Time 用 == 不相等？

== 还会比较 Location 和单调时钟信息。业务上比较瞬时点，应使用 Equal；需要统一表示时，可以在边界转成 UTC。

什么时候应该用 ParseInLocation？

只在输入没有时区信息、且业务已经明确它属于哪个地区时使用。输入已经带 Z 或数值偏移时，直接按 RFC 3339 解析更合适。

参考资料

• https://pkg.go.dev/time
• https://go.dev/src/time/time.go
• https://pkg.go.dev/encoding/json