Jiff 1.0 发布:Rust 生态的新一代日期时间库
Rust 日期时间库 Jiff 正式发布 1.0 版本。该库旨在通过 API 层面的设计,自动处理时区转换及夏令时(DST)相关的常见复杂问题,鼓励开发者专注于业务逻辑而非底层时间计算。Jiff 已在 Rust 生态系统中获得广泛采用。

关于名称发音,“Jiff”中的“g”发软音,类似于单词“gem”或“gigif”。
本次发布的官方博客重点介绍了 Jiff 的核心 API 特性。目标用户群体为需要高效、准确日期时间处理的 Rust 程序员。
内容概览
- Jiff 1.0 的承诺与稳定性
- 核心概念与术语定义
- 日期时间类型体系
- 时区定义与偏移处理
- 持续时间(Duration)操作
- 解析、格式化与本地化支持
- 日历运算与跨度管理
Jiff 1.0 的稳定性承诺
Jiff 目前已在多个知名生产环境中投入使用,包括 uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, uutils/coreutils,甚至作为 AWS LLRT 中临时实现的基础组件。鉴于其成熟度,项目正式将其标记为 1.0 版本。
开发团队计划无限期维护 Jiff 1.x 系列,除非发现严重的 API 缺陷。这一策略至关重要,因为 Jiff 旨在成为其他库公共 API 中的基础构建块。作为生态系统中的关键依赖项,任何不兼容的版本更新都可能对整个社区造成巨大冲击,因此破坏性变更将被严格避免。
有关 Jiff 0.2 至 1.0 之间的具体破坏性变更列表,请参阅官方 CHANGELOG。
核心概念与设计理念
日期时间库的核心功能在于协调计算机系统的绝对时间(如 Unix 时间戳)与人类感知的相对时间(如格里高利历、12/24 小时制时钟)。历史上,处理日期和时间极具挑战性,主要原因往往源于领域建模的不当。许多传统库将复杂性直接暴露给用户,导致容易出错。Jiff 的设计理念是将复杂性封装在可复用的代码包中,降低用户犯错的可能性。
快速上手
开发者可以通过以下命令创建一个新的 Cargo 项目并添加依赖:
mkdir jiff-playground
cd jiff-playground
cargo init --bin
cargo add jiff anyhow
$EDITOR src/main.rs
大多数示例均为独立的 Rust 程序,可直接替换 src/main.rs 中的代码并通过 cargo run 运行。
关键术语
为避免混淆,以下是 Jiff 涉及的关键时间概念定义:
- 公民时间 (Civil Time):即手表上显示的时间,也称为当地时间、普通时间或天真时间。它是特定地理区域内人类协调使用的协议。
- UTC (协调世界时):全球时间标准,作为各地公民时间的基础,最初旨在对应平均太阳时间。
- TAI (国际原子时):由原子钟测量的时间标准,不与平均太阳时间直接挂钩。
- 闰秒 (Leap Second):对 TAI 进行的调整,使其更接近平均太阳时间,从而构成 UTC 的基础。
- 统一时间:忽略秒级精度的 UTC。
日期时间类型体系
Jiff 的时间类型可以被视为一个层级结构,从基础组件组合成复杂的 ZonedDateTime:
- Civil Date:普通的格里高利日期,不关联特定地理位置。
- Civil Time:精确到纳秒的时钟时间,不关联特定地理位置。
- Civil DateTime:结合 Civil Date 和 Civil Time,提供无地点关联的日期和时间。
- Timestamp:代表自 Unix 纪元以来的纳秒数,是一个明确的物理时刻,不受地理位置影响。
- TimeZone:一组规则,用于在特定地理区域内将 Timestamp 映射为 Civil DateTime,反之亦然。
- ZonedDateTime:结合 Timestamp、Civil DateTime 和 TimeZone,表示特定地理位置下的确切时刻。
由于时区可以将 Civil DateTime 映射为 Timestamp,创建区域化日期时间只需提供这两个要素:
use jiff::civil;
let date = civil::date(2026, 11, 1);
let time = civil::time(17, 30, 0, 0);
let datetime = date.to_datetime(time);
// zdt 是 ZonedDateTime 的缩写
let zdt = datetime.in_tz("America/New_York")?;
assert_eq!(zdt.timestamp().as_second(), 1793572200);
Ok(())
}
另一种方法是仅使用 Timestamp 和时区,因为时区也能反向推导出具体的民用日期:
use jiff::{civil, Timestamp};
let timestamp = Timestamp::from_second(1793572200)?;
let zdt = timestamp.in_tz("America/New_York")?;
// 这是创建 civil datetime 的快捷方式
let expected = civil::date(2026, 11, 1).at(17, 30, 0, 0);
assert_eq!(zdt.datetime(), expected);
Ok(())
}
时区与偏移
时区偏移量表示为了从 UTC 得到公民时间所需调整的时间量。例如,纽约居民看到的 2026-11-01T17:30:00 对应于 UTC 时间的 2026-11-01T22:30:00(减去 5 小时):
2026-11-01T22:30:00 - 05:00 = 2026-11-01T17:30:00
每个划分的日期时间都包含关联的偏移量:
use jiff::{civil, tz, Timestamp};
let timestamp = Timestamp::from_second(1793572200)?;
let zdt = timestamp.in_tz("America/New_York")?;
assert_eq!(zdt.offset().seconds(), -(5 * 60 * 60));
let dt = civil::date(2026, 11, 1).at(17, 30, 0, 0);
let zdt = dt.in_tz("America/New_York")?;
assert_eq!(zdt.offset(), tz::offset(-5));
Ok(())
}
注意:America/New_York等字符串是 IANA 时区数据库标识符。IANA 数据库提供了一套可通过简短标识符引用的时区定义,如Australia/Sydney,Asia/Tokyo,Europe/Berlin。
更精确地定义,时区是一个与民用时钟一致的地理区域,它提供双向映射:
- 从某一瞬间(Timestamp)到与 UTC 的偏移量,应用该偏移量产生公民日期时间。
- 从公民日期时间到一个可能模糊的 UTC 偏移量,应用该偏移量产生一个瞬间。
这种从公民时间到偏移量的映射可能存在歧义,主要发生在夏令时转换期间:
- Fold(折叠):当时钟向后拨动时,某些时间点会出现两次(重复)。
- Gap(间隙):当时钟向前拨动时,某些时间点会被跳过(不存在)。
Jiff 默认采用“兼容”策略处理 Fold 情况,即选择第一次出现的时间:
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
let tz = TimeZone::get("America/New_York")?;
// 夏令时期间,纽约偏移量为 -04:00
let zdt = date(2026, 11, 1).at(0, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-4));
// 标准时间期间,纽约偏移量为 -05:00
let zdt = date(2026, 11, 1).at(2, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-5));
// 01:30AM 处于折叠区间,Jiff 默认选择第一次出现的 -04:00
let zdt = date(2026, 11, 1).at(1, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-4));
Ok(())
}
开发者可以通过底层 API 改变歧义解决策略:
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
let tz = TimeZone::get("America/New_York")?;
let dt = date(2026, 11, 1).at(1, 30, 0, 0);
// 默认行为,等同于 compatible
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// 始终选择较早的时间
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-4));
// 始终选择较晚的时间(即第二次出现的 1AM)
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-5));
// 如果存在歧义则报错
assert_eq!(
tz.to_ambiguous_zoned_datetime(dt)
.unambiguous()
.unwrap_err()
.to_string(),
"error converting datetime to instant in time zone America/New_York: \
datetime is ambiguous \
since it falls into a fold between offsets -04 and -05",
);
Ok(())
}
对于 Gap(间隙),同样适用类似逻辑。例如 2026 年 3 月 8 日 2AM 时钟向前跳至 3AM:
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
let tz = TimeZone::get("America/New_York")?;
let dt = date(2026, 3, 8).at(2, 30, 0, 0);
// 默认策略选择间隙后的时间
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// 选择间隙前的时间
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-5));
// 选择间隙后的时间(同 compatible)
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-4));
// 存在歧义时报错
assert_eq!(
tz.to_ambiguous_zoned_datetime(dt)
.unambiguous()
.unwrap_err()
.to_string(),
"error converting datetime to instant in time zone America/New_York: \
datetime is ambiguous \
since it falls into a gap between offsets -05 and -04",
);
Ok(())
}
持续时间(Durations)
Jiff 提供两种核心持续时间类型:
- Span:一种混合持续时间类型,同时包含日历单位(年、月、周、天)和物理时间单位(小时、分、秒等)。它保留了各个单位的独立值,功能强大。
- SignedDuration:
std::time::Duration的有符号版本,始终对应 96 位整数纳秒数。仅能表示物理时间(小时及以下),不能表示日历单位(天及以上)。
建议尽可能使用 Span。例如计算两个日期之间的天数:
use jiff::civil::date;
let d1 = date(2024, 2, 1);
let d2 = date(2024, 3, 1);
let span = d2 - d1;
assert_eq!(span.get_days(), 29);
// 等价写法
assert_eq!(d1.until(d2)?.get_days(), 29);
// 顺序颠倒结果为负
let span = d1 - d2;
assert_eq!(span.get_days(), -29);
Ok(())
}
持续时间也可以添加到日期中:
use jiff::{civil::date, ToSpan};
let d1 = date(2024, 2, 1);
// 使用 ToSpan 扩展 trait
let span = 29.days();
assert_eq!(d1.checked_add(span)?, date(2024, 3, 1));
Ok(())
}
涉及 Span 的操作通常也有对应的 SignedDuration 版本:
use jiff::{civil::date, SignedDuration};
let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
let sdur = SignedDuration::from_mins(90);
assert_eq!(dt1.checked_add(sdur)?, date(2024, 2, 1).at(19, 0, 0, 0));
Ok(())
}
注意上述示例中使用了 civil::DateTime 以展示物理时间单位的加法。但 Span 因其组合所有单位的能力,也能完成相同任务:
use jiff::{civil::date, ToSpan};
let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
let span = 1.hour().minutes(30);
assert_eq!(dt1.checked_add(span)?, date(2024, 2, 1).at(19, 0, 0, 0));
// 可以混合日历单位和物理单位
let span = 1.month().hours(1).minutes(30);
assert_eq!(dt1.checked_add(span)?, date(2024, 3, 1).at(19, 0, 0, 0));
Ok(())
}
总结而言,优先使用 Span;若需更轻量或更快的性能,且仅涉及物理时间,可使用 SignedDuration。





