Rust 时间库 Jiff 1.0:1:30 出现两次的那晚,与 25 小时的一天

开源Rust

2026 年 11 月 15 日,Andrew Gallant(网名 burntsushi,ripgrep 与 Rust regex 库的作者)发布了日期时间库 Jiff 的 1.0.0 版本。这个库已经进入一批核心工具的生产依赖:uv、Cargo、Starship、fd、Nushell、mise、Jujutsu、uutils/coreutils 都在用,AWS 的 LLRT 运行时还基于它实现了 JavaScript 的 Temporal 提案。仓库 2024 年 2 月创建,67 位贡献者参与,GitHub 仓库卡片显示有 3.8 万个项目依赖它,星标 3088。发布帖在 Hacker News 拿到 272 分、59 条评论,Lobsters 同日上榜。

Jiff 1.0 的发布说明里写了一句少见的承诺:除非 API 出现重大缺陷,1.x.y 版本线将无限期维护下去。作者的理由很具体,Jiff 的定位是生态基石,会出现在其他库的公共 API 签名里,任何不兼容升级都会在整个依赖树上放大成迁移成本。

时间的两套语义

日期时间处理的老大难,源头在于两套时间语义同时存在。机器用的是 Unix 时间戳,一条单调递增的纳秒计数;人用的是格里历加时钟,2026 年 11 月 17 日 7 点这种写法。时区就是两者之间的换算规则。burntsushi 的判断是,多数日期时间库的痛点出在领域建模:库没有把复杂度封装好,而是转嫁给了调用方。Jiff 的类型系统按「洋葱」分层:civil::Date、civil::Time、civil::DateTime 描述挂钟时间,Timestamp 描述绝对时刻,TimeZone 承担双向换算,ZonedDateTime 三者合一。RFC 9557 语法的字符串 2026-04-05T02:30+11:00[Australia/Sydney] 可以直接 parse 成 ZonedDateTime。

凌晨 1:30 出现了两次

2026 年 11 月 1 日凌晨 2 点,纽约把时钟拨回 1 点,切换回标准时间。于是那晚的 1:30 存在两个版本,一个落在 UTC-4,一个落在 UTC-5。反过来在 2026 年 3 月 8 日,时钟从 2 点直接跳到 3 点,2:30 在纽约压根不存在。前者叫 fold(折叠),后者叫 gap(间隙)。

Jiff 给了四种显式策略处理这类歧义:compatible 是默认值,fold 取第一次出现、gap 取拨针之后的时间;earlier 和 later 分别强制取早取晚;unambiguous 则要求无歧义,否则返回错误。unambiguous 的报错信息会写明原委:datetime is ambiguous since it falls into a fold between offsets -04 and -05。要拿回控制权,调用方从 in_tz 换成 TimeZone::to_ambiguous_zoned_datetime,四种策略各是一个链式方法。

Jiff 处理夏令时 fold 的四种消歧策略(图片来源:burntsushi.net)

解析方向同样照顾了这种歧义。2026 年 4 月 5 日凌晨 3 点悉尼拨回时钟,2:30 那晚出现两次。RFC 9557 字符串 2026-04-05T02:30[Australia/Sydney] 交给 Jiff,默认选第一次出现;字符串里一旦写明偏移,变成 2026-04-05T02:30+11:00[Australia/Sydney] 或 +10:00 版本,时刻唯一确定,两种写法各自解析到不同瞬间。要在解析阶段更换消歧策略,标准库的 FromStr trait 表达不了,Jiff 为此暴露了 fmt::temporal::DateTimeParser 底层接口,Disambiguation 枚举逐项可选。除 Temporal 风格外,strptime/strftime 与 RFC 2822 也各有实现,邮件头这类场景可以直接从字节串解析出 Timestamp。

「明天」偶尔有 25 个小时

2024 年 11 月 3 日纽约完成秋季拨钟,那天实际长度为 25 小时。Jiff 里 ZonedDateTime 的 tomorrow() 跨过这一天时,返回的日期是 11 月 3 日同一个挂钟时刻,两个时刻相减得到的物理时长打印出来是 25h。日历算术同样按人的直觉走:5 月 31 日加一个月得到 6 月 30 日,闰年 2 月 29 日加「一年两个月零五天」得到 2025 年 5 月 4 日。这类运算全部提供 checked_add 的返回 Result 版本,用户输入场景下溢出范围会得到错误而非 panic。

tomorrow() 与 25 小时的那一天(图片来源:burntsushi.net)

Span 与 Duration 的名字之争

时长在 Jiff 里分成两个类型。Span 是主力,可以混合日历单位和物理单位,1.month().hours(1).minutes(30) 是合法写法,各单位数值独立保存;SignedDuration 则是 std::time::Duration 的带符号版本,纯粹表示物理时长。起名时作者刻意避开了 Duration,防止和标准库类型混淆。

Span 保留单位信息带来一个特性:2 小时和 120 分钟在内存里是两个不同的值,fieldwise 比较不相等,compare 按物理时长比较才相等。这对应现实里的习惯,电影片长习惯写 150 分钟而不会换算成 2 小时 30 分。Span 做取整运算时必须给出 relative 参照日期,一个月对应的物理时长取决于锚在哪一天。Jiff 深受 JavaScript Temporal 提案影响,两者的互译几乎逐行对应:把「1 个月 1 天 1 小时」相对 2022-01-01 取整到天,Temporal 与 Jiff 都得到 P32D。

1.0 承诺了什么

1.0.0 最大的破坏性变更是类型改名:Zoned 改为 ZonedDateTime,相关 API 同步更名,其余变更影响面小。MSRV 提到 Rust 1.85,许可证是 Unlicense。格式化方面同时支持 Temporal 风格、POSIX strptime/strftime 和 RFC 2822,范围限制在格里历、正负 9999 年。

chrono 维护者的告别

Jiff 1.0 发布帖的评论区出现了一段少见的对话。quodlibetor 自述维护 chrono 约五年,接手动机就是认为 API 有改进空间;但用户真正需要的是 API 稳定,每一步改进都遭遇阻力,最终因看不到改进路径、精力耗尽而离任。chrono 的初代作者 lifthrasiir 也跟帖致谢,并坦言当时的 API 设计留下了遗憾。chrono 仓库今年 1 月由维护者 djc 开出 Soft-deprecating chrono and chrono-tz 的 issue(#1768),建议新项目直接选用 Jiff。有开发者在讨论中表示从 chrono 切换到 Jiff 的迁移成本很低。

标准库的门外

评论区也有人追问,为什么这样的基础设施不进 Rust 标准库。Rust 核心团队成员 Josh Triplett 的回应是,标准库要避免成为「代码死去的地方」,官方正在推进 std-replacement-data 数据集,跟踪哪些生态库适合收编进标准库。另有开发者指出,日期时间恰好是过早进入标准库风险最高的领域之一,API 一旦定型就要背几十年。持相反立场的评论引用了 Java 的先例:java.time 证明标准库可以把这件事做好,前提是此前两代失败 API 交够了学费。Jiff 自己也划了边界:测程序耗时应该用 std::time::Instant 的单调时钟,天文尺度的时间换算,burntsushi 本人在评论区推荐了另一个库 hifitime。

评论区还有一条高赞玩笑,Jiff 的发音按 gif 的软 g 读,和 gem 押韵,一场老梗论战在时间库的发布帖里重演了一遍。

来源:burntsushi.net 官方博文 · GitHub: BurntSushi/jiff · chrono#1768 · Hacker News 讨论