REST API 中的时区：如何设计时间字段

API 是系统间传递时间的关口。时间字段的格式和时区约定不清晰，会让客户端和服务端都陷入混乱。

推荐格式

使用 ISO 8601 / RFC 3339，并带时区信息：

• 2027-01-01T12:00:00Z：UTC 瞬间
• 2027-01-01T20:00:00+08:00：带偏移的瞬间
• 2027-01-01：纯日期，不含时间

避免使用 2027-01-01 12:00:00 这类无时区字符串。

瞬间 vs 本地时间

事件发生时刻、创建时间、过期时间应使用带偏移的时间。营业时间、每日提醒等“本地规则”则需额外提供时区 ID，如 Asia/Shanghai。

设计建议

• 在文档中明确字段含义和时区约定
• 服务端统一以 UTC 返回瞬间
• 日期字段与时间字段分开
• 不要用偏移量代替时区 ID 表示规则
• 对夏令时边界做兼容说明

客户端处理

客户端应解析偏移并转换为用户时区展示，而不是截取字符串。对日期字段避免用本地时区解析，否则可能偏移一天。

清晰的 API 时间约定，是跨时区系统可靠协作的基础。