时区（Timezone）说明文档

本档介绍项目中时区的用法、格式、命名规范及实现建议。当前项目使用类似 Asia/Shanghai 这样的时区标识（IANA 时区），默认时区为 UTC。时区属于用户偏好设置（与语言同级），用于按用户所在时区展示具体时间（例如邮件、UI 时间戳等）。

关键结论（快速阅读）

我们使用的是 IANA 时区数据库（又称 tz database / Olson database），示例格式为 Region/City，如 Asia/Shanghai、Europe/Berlin、America/New_York。

默认时区为 UTC（后端内部统一以 UTC 存储时间）；用户可以设置自己的时区，系统按用户时区展示时间并显示与 UTC 的偏移（例如 2026/01/15 15:19:33 (UTC+8)）。

API/前端传入的时区建议使用 IANA 名称；支持大小写容错但会规范化为标准形式（建议使用 Asia/Shanghai 的首字母大写形式）。

注意夏令时（DST）和有些时区带分钟偏移（如 Asia/Kolkata 为 UTC+05:30）。

专业术语说明

IANA Time Zone Database（IANA tzdb / tz database / Olson）：行业标准的时区标识库，使用格式 Area/Location（例如 Asia/Shanghai）。

UTC（Coordinated Universal Time）：协调世界时，作为系统内部统一存储与对齐时间的基准。

偏移（Offset）：时区相对 UTC 的差值，如 UTC+8、UTC-5、UTC+05:30。

我们的策略与行为（总体说明）

存储

所有时间在数据库与日志中统一以 UTC 存储（ISO 8601 / RFC3339 推荐格式，如 2026-01-15T07:19:33Z）。

用户的时区单独保存为字符串（IANA 名称），例如 Asia/Shanghai。

展示

向用户展示时间时，服务器或客户端根据用户设置的时区将 UTC 时间转换为该时区时间，并在显示中附带 UTC 偏移标识：

示例：若 UTC 时间为 2026/01/15 07:19:33 (UTC)，用户时区为 Asia/Shanghai（UTC+8），邮件/界面显示：

2026/01/15 15:19:33 (UTC+8)

如果用户时区为 UTC，则显示：

2026/01/15 07:19:33 (UTC)

默认与回退

新用户默认时区：UTC。

如果客户端未提供或传入非法时区，后端回退使用用户配置的时区（若无则使用 UTC）。

时区与语言的关系

时区与语言同属用户偏好设置的两个独立维度：语言决定文本/翻译，时区决定时间展示。两者互不替代。

API 交互建议

客户端可通过请求头 X-Timezone（或 x-timezone）传递用户当前时区，例如：

X-Timezone: Asia/Shanghai

后端解析时应：

接受 IANA 名称（大小写容错），并规范化为标准格式（首字母大写的 Region/City 格式）。

验证该时区在 tz database 中是有效的；若无效则返回 400 或使用默认（视业务而定）。

显示格式建议

建议统一时间展示格式（可调整为项目标准），例如：

日期时间（24小时制）：YYYY/MM/DD HH:mm:ss (UTC±HH[:MM])

示例：

2026/01/15 15:19:33 (UTC+8)

2026/01/15 07:49:33 (UTC+5:30)

2026/01/15 02:19:33 (UTC-05:00)

如果需要本地化（语言对应的日期格式），可在时区展示外依语言格式化日期字符串，但仍建议附上 (UTC±offset) 以避免歧义。

夏令时（DST）与注意事项

IANA 时区包含历史与夏令时规则，使用 IANA 名称可以自动处理 DST（例如 America/New_York 在夏季为 UTC-4，冬季为 UTC-5）。

注意：并非所有时区都有 DST（例如 Asia/Shanghai 目前无 DST）。

对于跨日历或跨长期调度任务（如定时任务、订阅、日历事件等），务必同时保存原始时区，以正确处理 DST 变化。

存储与调度的最佳实践

在 DB 中只存 UTC 时间（timestamp with time zone / UTC epoch），并独立记录用户时区字符串。

若有用户创建的“定时事件”（如用户在午夜触发某事），保存：

事件的 UTC 时间（计算后的时间）

事件的原始表达（如 “每天 09:00”）以及用户时区（Asia/Shanghai），以便未来按 DST/规则准确重算。

对于报告/历史记录，保存原始 UTC 时间并展示用户可读的本地时间（带 offset）。

进行时区规则或 tzdb 升级前，评估对已存定时任务的影响。

校验规则（后端实现建议）

验证传入时区是否为合法 IANA 名称（可使用语言运行环境的 zoneinfo/zoneinfo database 来验证）。

对大小写做容错（asia/shanghai → 规范化为 Asia/Shanghai），但建议对外文档与客户端使用标准大小写。

若验证失败：返回 400 + 明确错误信息，或使用用户已保存时区或 UTC 作为回退。

实现示例（代码片段）

Go（使用标准库 time 和 IANA 名称）

JavaScript（Node/browser — Intl API）

若需精确 UTC+08:00 风格偏移，可用 getTimezoneOffset（注意返回分钟且基于运行时环境的时区）或借助库（luxon / moment-timezone）。

Python（zoneinfo、datetime）

PostgreSQL（示例）

假设 ts_utc 列为 timestamp with time zone（存储为 UTC）：

（Postgres 的时区/格式函数较多，视版本调整语法。）

测试要点

用不同时区用户测试时间展示是否正确（含正负偏移、半小时偏移如 Asia/Kolkata）。

测试跨 DST 边界的事件展示与调度（例如美东时间的 DST 切换日）。

测试非法、未知时区输入的回退逻辑与错误码返回。

测试邮件/通知中时间字符串是否包含偏移，避免歧义。

常见问答（FAQ）

Q: 为什么不直接在 DB 存本地时间？
A: 存 UTC 可以避免时区转换中的混淆、简化合并/比较与跨时区统计，前端/展示层再按用户时区转换。

Q: 用户使用 asia/shanghai（小写）会被接受吗？
A: 我们建议使用标准格式 Asia/Shanghai。服务器应对大小写做容错和规范化，但文档与对外接口示例建议使用标准大小写。

Q: 时区字符串是否会随 tzdb 升级发生变化？
A: tzdb 会更新规则（包括历史记录、DST 规则），但时区标识（如 Asia/Shanghai）一般保持稳定。定期更新服务端的 tz 数据库是必要的。

Q: 如果用户旅行到另一个时区，时间展示如何处理？
A: 若用户未更改其个人设置，系统继续使用该用户配置的时区；如果需要实时按设备时区展示，则客户端应在请求时发送当前 X-Timezone。

最佳实践小结

后端统一以 UTC 存储时间，前端/邮件展示时按用户时区转换并显示 (UTC±offset)。

时区使用 IANA 名称（Asia/Shanghai 等），验证并规范化输入。

保存用户时区与原始事件时区（若有），处理 DST 时需保留足够元数据。

在 API 文档中明确 X-Timezone 的使用与示例，并提示开发者使用 IANA 名称。

在多语言邮件/通知中同时提供本地化时间字符串与 UTC 偏移，避免歧义。

时区相关

时区（Timezone）说明文档#

关键结论（快速阅读）#

专业术语说明#

我们的策略与行为（总体说明）#

API 交互建议#

显示格式建议#

夏令时（DST）与注意事项#

存储与调度的最佳实践#

校验规则（后端实现建议）#

实现示例（代码片段）#

Go（使用标准库 time 和 IANA 名称）#

JavaScript（Node/browser — Intl API）#

Python（zoneinfo、datetime）#

PostgreSQL（示例）#

测试要点#

常见问答（FAQ）#

最佳实践小结#