深度解析塑造未来的技术文章。

Jiff vs Chrono:Rust 日期时间库怎么选

对比 Rust 日期时间库 Jiff 与 chrono:夏令时边界情况、API 易用性,以及各自最适合的场景,来自两边都踩过坑的实践者。

两个风格化的重叠时钟,一个机械、一个有机,暗示时区切换。
日期时间的 bug 很少让程序直接崩溃,它们只是悄悄给你一个错误的时间。

每隔几年,总会有某个倒霉的工程师发现,纽约时间 2026-11-01 01:30 居然出现了两次,而他的调度器也因此提前一小时触发了账单任务。日期时间相关的 bug 通常不会让程序崩溃,而是悄无声息地污染你的数据。所以,Ripgrep 作者 Andrew Gallant 推出的新 Rust 日期时间库 Jiff 1.0 之所以值得关注,不只是又一个 crate 发版而已。它逼着我们回答一个实际问题:Jiff vs chrono,你的下一个 Rust 项目到底该用哪个?

Rust 日期时间的踩坑简史

Rust 在这个问题上早就栽过跟头,这段历史很有启发性。Chrono 诞生于语言的 1.0 之前,当时它和 time 一起从标准库中被拆分出来,作为“让标准库体量合理化”大清理的一部分。将近十年间,它都是默认答案。大体上它能用,但它的 API 层层堆叠:NaiveDateTime、DateTime<Utc>、DateTime<Local>、DateTime<FixedOffset>,还有一个 TimeZone trait,而大多数人实际只会接触其中两个实现。类型系统允许你做很多语义上说不通的事,比如把一个朴素日期时间加到一个带时区的日期时间上,然后得到一个自信满满却是错的结果。

维护层面的情况同样重要。Chrono 一度几乎处于被弃养的状态,即便后来的维护者,也描述过推进工作的艰难:用户把 API 稳定性当成不可触碰的东西,每一步小小的改进都会遭遇阻力。一位前维护者说得很直接:chrono 最大的卖点已经从设计变成了稳定性。这是任何长寿库都可能掉进去的陷阱,即已安装的用户基数本身变成了产品。time crate 尝试了另一条路线,核心更干净,但多年来对完整的时区处理一直拖着没做。与此同时,生态里的应用越来越多地依赖“下个三月柏林是什么时间”这类问题,它已经成了承重的核心需求。

Jiff 借鉴的是一种老思路,不管它是否明说:Rico Mariani 在 2000 年代中期提出的 API 设计“成功之坑”(pit of success)理念。让简单的路径同时也是正确的路径。Gallant 的观点是,日期时间的难点源于糟糕的领域建模,而那些把歧义推给用户的库,比如“这是一个朴素日期时间,祝你好运”,实际上是把最难的问题外包了出去。这和 Rust 所有权模型背后的直觉一脉相承:让机器吸收复杂性,而不是让人去承担。

Jiff 如何建模时间:洋葱模型

Jiff 的核心设计是 Gallant 所说的“日期时间洋葱”。从内到外,各层如下:

  • civil::Date:公历日期,不带地点信息。你的生日就是这一类。
  • civil::Time:挂钟时间,精度到纳秒,不带地点信息。
  • civil::DateTime:日期加时间,同样不带地点信息。这正是 chrono 所谓的 naive。
  • Timestamp:无歧义的时间点,即自 Unix 纪元起的纳秒数。
  • TimeZone:描述某个地区时间点与本地时间之间映射规则的时区规则。
  • ZonedDateTime:把以上全部组合起来:时间点、本地时间和时区。

这种设计的好处是,类型名称与你脑中已有的心智模型一一对应。Timestamp 是从数据库或系统调用中拿到的东西,civil::DateTime 则是人们在日历邀请里写下的时间。没有时区,二者之间就无法转换,而 Jiff 把这种转换做成了显式的、可能失败的、带时区标注的操作。对比 chrono,它其实也有类似的区分,但更容易混淆:NaiveDateTime::and_utc() 会毫不犹豫地给一个挂钟时间贴上时区标签,却不去追问这个挂钟时间是否真实存在过。

Jiff 的 API 用起来刻意保持温和。你可以从两个方向构造带时区的日期时间,即本地时间加时区,或者时间戳加时区,API 都会在这里与你会合:

use jiff::civil;
fn main() -> anyhow::Result<()> {
// Start from what a human would write on a calendar.
let dt = civil::date(2026, 11, 1).at(17, 30, 0, 0);
let zdt = dt.in_tz("America/New_York")?;
assert_eq!(zdt.offset().seconds(), -(5 * 60 * 60));
// Arithmetic on the civil parts stays civil:
let tomorrow = zdt.date().tomorrow()?;
assert_eq!(tomorrow, civil::date(2026, 11, 2));
Ok(())
}

夏令时:Jiff 的价值所在

这是区分日期时间库设计水平高低的典型场景。2026 年 11 月 1 日凌晨 2 点,纽约的时钟会回拨,于是 1 点到 2 点这一小时会出现两次。那么当用户输入“11 月 1 日凌晨 1:30”时,你该怎么办?Chrono 历来的做法是 LocalResult:一个可能是 Single、Ambiguous 或 None 的枚举。而大量生产代码会直接 unwrap、丢弃结果,或者模式匹配写错。歧义确实暴露出来了,但处理它的负担也每次都压在了你身上。

Jiff 的做法是选定一个合理的默认值,同时让其他选项只需一次方法调用即可获得。默认的“compatible”策略会把重复时段解析为较早的那次出现,这与大多数日历软件以及所有主流操作系统的行为一致。如果你需要更细的控制,完整的决策树也都摆在那里:

use jiff::{civil::date, tz::TimeZone};
fn main() -> anyhow::Result<()> {
let tz = TimeZone::get("America/New_York")?;
let dt = date(2026, 11, 1).at(1, 30, 0, 0);
let amb = tz.to_ambiguous_zoned_datetime(dt);
let earlier = amb.earlier()?;  // offset -04 (EDT), first 1:30
let later = amb.later()?;      // offset -05 (EST), second 1:30
// Or refuse to guess entirely:
assert!(tz.to_ambiguous_zoned_datetime(dt).unambiguous().is_err());
Ok(())
}

时间缺口也是同样的处理方式:当时钟向前拨动,凌晨 2:30 根本不会出现时,Jiff 默认向前调整,同样你也可以覆盖这一行为。这里的设计判断带有明确的立场,我认为也是正确的。大多数处理歧义时间的代码并没有明确的策略,它们只是在等待十一月的那个 bug。默认采用用户在手机上已经习惯的行为,同时把逃生口保持可见并且有类型约束,这正是“成功之坑”在实践中的含义。这种思路与好的默认值设计是相通的,参见 手写日期运算:规则是可以学会的,但你不应该在每个调用点都重新推导一遍。

一条抽象的带状时间线,其中一处折返形成重复,一处断开形成缺口。
重复与缺口:本地时间无法干净映射到时间点的两个位置。

时长、跨度与“一个月”的难题

如果你向 chrono 要一个“一个月”的时长,会很失望。它的 Duration 是固定的秒数,因为一个月并不对应固定的任何单位。这种设计本身站得住脚,但也意味着日历运算(比如“1 月 31 日加三个月”)变成了你自己的问题。Jiff 的 Span 类型走的是另一条路:它可以同时保存从年到纳秒的混合单位,并且运算会以日历感知的方式进行。1 月 31 日加一个月,得到的是 2 月 28 日(或 29 日),而不是 3 月 3 日。在夏令时切换前一晚,给带时区的日期时间加一天,实际加上的是一个日历日,它可能是 23 或 25 小时,而这正是人们说“明天同一时间”时的真实含义。

“经过的时间”与“日历时间”之间的区别,是日期时间编程中最容易混淆的概念,而且它几乎处处都被混淆。Java 最初的 java.util.Date 把两者混为一谈,而 Java 8 的 java.time 包(本身借鉴了 Joda-Time)将 Duration 与 Period 分开,这一改动很有价值。JavaScript 的 Temporal 提案也做了同样的拆分。Jiff 很自然地延续了这一脉络:日期时间设计中的好想法在过去二十年里不断趋同,而 Jiff 本质上就是这一共识的 Rust 表达,就像 酝酿多年的 Rust 语言特性 最终以十年争论的精炼版本落地一样。

Jiff 还提供“友好”的时长格式,像 2h 30m 或 P1DT2H 这样的字符串可以自然地解析和输出,此外还支持 strptime/strftime 风格的格式化,并可选集成 ICU4X 以输出与地区相关的格式。这些功能听起来像是基本配置,但任何为日志流水线手写过 chrono 格式字符串的人都知道,它们能免去多少麻烦。

Jiff vs Chrono:各自何时胜出

功能讲够了,下面是带有明确观点的坦诚对比。

chrono 仍然占优的场景

惯性本身就是一种优势。Chrono 存在于大量 Rust 生态的依赖树中,出现在无数公开 API 里,并且有一支可靠的团队在维护。如果你的代码库已经熟练使用 chrono,你的时间戳只是 UTC 时间点(比如指标流水线、日志信封、内部 RPC),而且团队熟悉它的各种坑,那么迁移的收益其实很有限。Chrono 对 std 可选、对 no_std 友好的特性,在嵌入式场景中依然重要。而如果你做的是某些特殊需求,比如百万年尺度的轨道力学,或者 TAI、UT1 这类替代时间尺度,那么这两个库都不是真正的答案。你大概会包装其中一个用于字符串解析,同时保留自己的内部表示,而 chrono 在边缘处的简洁对此已经足够。

还有一个我在实践者中看到过的合理反方观点:有些人确实更喜欢 chrono 的显式性。LocalResult::Ambiguous 会逼你去思考。如果你的领域里,猜错了夏令时重复时段会带来法律或经济后果,比如薪资、能源结算、交易,那么你或许希望库永远拒绝猜测。Jiff 通过 unambiguous() 也能做到这一点,但 chrono 让这条路径成为阻力最小的选择。这个观点也有道理。

Jiff 胜出的场景

其他几乎所有场景都是。任何涉及本地时间的应用,比如调度、日历、面向用户的日期,或者任何跨时区的业务,用 Jiff 都会得到明显更好的结果。类型名称本身就在传授领域知识。夏令时歧义有合理的默认值,并且提供有类型约束的逃生口,而不是让你在凌晨 2 点处理错一个枚举。Span 开箱即用就能正确地做日历运算。解析与格式化覆盖了人们真正会写的友好格式。而 1.0 版本的承诺也很重要:Gallant 明确表示打算无限期保持 API 稳定,这样 Jiff 就能出现在其他库的公开 API 中,而这恰恰是让 chrono 的错误变得难以修正的那种特性。目前的采用者名单也印证了这一雄心:uv、Cargo、Starship、fd、Nushell、Jujutsu 和 uutils 都在使用它,AWS 的 LLRT 也基于它实现了 Temporal。

总有人会问性能问题,我先说结论:两个库都足够快,日期时间处理从来不会成为你的瓶颈。Jiff 内置了一份压缩版的 IANA 时区数据库(并对是否使用 rearguard tzdata 有清晰且经过深思熟虑的说明),也可以直接使用系统的时区数据库。在这个领域,正确性远比微基准测试重要,单纯因为速度来选型就是失职。一个在 50 纳秒内给出的错误答案,依然是错的。

一个处处都要求你处理歧义的日期时间库,并不会因此更诚实,它只是把自己最难的问题外包给了最不具备解决能力的人:也就是你,在某个调用点,匆匆忙忙地解决。

对 API 设计的更大启示

抛开日期本身,Jiff 其实是一个更广泛论点的案例研究:库应该封装领域复杂性,而不是原样转发它。IANA 时区数据库正如批评者所言,是一个面向程序员的产物,以地点为中心,历史上极其详尽,充满了用户永远不会去输入的标识符。一个偷懒的库会把这些原始细节直接暴露出来,还美其名曰灵活性。一个好的库则会吸收这些复杂性:提供默认的消歧策略、友好的解析,以及映射到人类概念的类型名称。在其他领域,你也能看到同样的张力,规范与可用实现之间的差距正是大多数 bug 藏身的地方,而日期时间处理恰好是这道鸿沟最典型的栖息地。

这也是一个关于生态耐心的故事。Rust 等了十年才迎来它的“权威”日期时间库,就像它也曾等待多年,让 async 逐渐成熟,等待 never type 稳定一样。等待的代价,是为了把模型做对,而不是把第一个能用的草稿固化下来。Chrono 并不是失败品,它是生态在当时所需要的草稿。但草稿是可以被修订的。

我的建议

新的 Rust 项目?用 Jiff,不必纠结。它的 API 更好,夏令时处理默认更安全,1.0 的稳定性承诺也明确,而且生态的势头也很明显,Cargo 和 uv 可不会随便采用某个 crate,所以你迟早会频繁遇到它。面向用户的场景用 ZonedDateTime,存储和网络协议格式用 Timestamp,只有在地点确实不相关时才用 civil 类型。

已有一个能正常运行的 chrono 代码库?那就保持现状,除非你正在处理大量本地时间相关的功能,并且 chrono 的各种坑已经实际拖累了你。两个库通过时间戳和 ISO 字符串可以很好地互操作,所以部分迁移,比如调度模块用 Jiff、其余部分仍用 chrono,是一种合理的策略,而不是妥协。

无论你选哪个,最深的收获是:日期时间处理之所以难,是因为这个领域本身就不可约地古怪,闰秒、重复、缺口、长度可变的月份,还有会因政令而改变的政治时区。库能做的最好的事,就是选对默认值,诚实地命名,并让逃生口触手可及。Jiff 三者都做到了。从 Joda-Time 到 java.time 再到 Temporal,二十年的日期时间库演进最终收敛到同一个模型,这是有原因的。看到 Rust 终于拥有了自己的版本,确实令人欣喜。