设计时区转换 API - 为真实应用构建稳健端点

输入输出格式决策

第一个设计选择是输入和输出格式。要求使用 ISO 8601(例如 2026-05-15T16:00:00+09:00),并拒绝缺少时区信息的输入。接受不带偏移量的时间戳会产生该值属于哪个时区的歧义,这种歧义不可避免地会泄漏到生产环境中出现的 bug 里。

对于目标时区,应接受 IANA 名称(Asia/Tokyo)而非 UTC 偏移量(+09:00)。偏移量只描述某一时刻的差值,无法捕获夏令时规则。America/New_York 让 API 自行判断输入是否处于夏令时或标准时间,并自动应用正确的偏移量(-4 或 -5)。

安全处理夏令时转换

夏令时转换会创造不存在的时间和重复的时间。在春季(例如凌晨 2:00 跳到 3:00),2:00-2:59 这个范围根本不存在。在秋季(例如凌晨 2:00 回拨到 1:00),1:00-1:59 这个范围出现两次。API 必须明确处理这两种情况,而非依赖库的默认行为。

对于不存在的时间,有三种选择:返回错误、向前舍入到转换后的时间(2:30 变为 3:00)、或向后舍入到转换前的时间(2:30 变为 1:30)。对于重复的时间,询问客户端应用哪个偏移量,或默认使用转换前的规则。在每种情况下,响应中都应包含一个标记,注明进行了调整,以便客户端在需要时能够检测并作出反应。

管理 IANA 数据库

IANA 时区数据库(tzdata)每年更新 3 到 10 次。每当一个国家采用、修改或废除夏令时,就会发布新版本。保持 API 服务器的 tzdata 最新是不可妥协的运维要求;否则,某些国家的未来时间戳将返回错误结果,而且不会引发任何错误。

tzdata 更新可能带来向后兼容性影响。时区名称有时会合并(Asia/Calcutta 变为 Asia/Kolkata),历史数据有时会被修正。推荐的模式是将已弃用的名称作为输入别名接受,同时始终在响应中返回规范名称。这样客户端可以按自己的节奏迁移,而 API 接口保持最新。

错误处理 - 让失败显式化

时区转换 API 必须处理格式错误的日期时间、未知的时区名称、超出支持范围的日期(非常久远的过去或未来),以及前面提到的夏令时间隙时间。每种错误情况都值得拥有不仅仅是 HTTP 状态码,还有机器可读的错误代码和帮助开发者修复问题的人类可读消息。

注意部分有效的输入。像 2026-02-30T10:00:00+09:00 这样的日期时间(2 月 30 日不存在)可能会被某些库静默更正为 3 月 2 日。安全的 API 行为是明确拒绝此类输入而非自动更正;客户端不应看到针对一个他们未指定的日期成功处理。今天的一个错误好过将来神秘的数据质量问题。

性能与缓存策略

转换本身的计算开销很小,但在高负载下缓存会有帮助。缓存键要小心:相同的输入时间戳和目标时区在不同 tzdata 版本下可能返回不同结果。将缓存失效与 tzdata 更新绑定,以便当底层规则变更时过期的转换结果会消失。

一个接受多个时间戳的批量转换端点可以减少客户端的往返开销。一个日历应用在渲染不同时区的一个月事件时,可以发出一个批量请求而非 30 个单独请求,同时改善客户端感知的延迟和服务端吞吐量。批量 API 在速率限制和计量方面也比大量单项请求更容易管理。