紧凑时长格式规范 2.0 - Compact Duration Format v2.0

1 版本说明

本文定义紧凑时长 ¹格式（Compact Duration Format）的 2.0 版。1.0 定义的表示在 2.0 中仍然有效，数值含义不变。

与 1.0 相比，2.0 明确以下内容：

• 完整的词法与语法；
• 合法形式与规范形式；
• 单位进位与数值范围；
• 非负约束；
• 展示形式的选择原则；
• 统一的失败情形。

3w2d1h20m33s 等 1.0 写法在 2.0 中仍然合法，数值含义不变。

2 规范用语

本文中的「必须」「不得」「应」「不应」「可以」按 RFC 2119 解释：

3 设计目标

工程配置里常见的 timeout: 3600 需要翻文档确认单位；自由文本 2小时30分 人类易读但机器难以统一解析；ISO 8601 的 P3W2DT1H20M33S 足够严谨，但在配置、日志和状态描述中读写成本偏高。

紧凑时长格式面向项目内部的高频读写场景，目标如下：

• 人工可以直接读出时长；
• 机器可以无歧义地解析为精确数值；
• 任意两个表示可以按数值比较；
• 展示可以优先人类阅读；
• 规范只约束语法和数值语义，不约束展示形式的选择。

本格式是项目级规范，不追求覆盖 ISO 8601 的全部日历语义，也不宣称在语法上与其兼容。

4 语法

Duration = UnitPart+ ;
UnitPart = Number Unit ;
Number   = Digit+ ;
Digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
Unit     = "w" | "d" | "h" | "m" | "s" | "ms" | "us" | "ns" ;

w → d → h → m → s → ms → us → ns

5 合法形式与规范形式

本规范定义两种表示：合法形式和规范形式。

• 合法形式是语法上可以解析的表示。
• 规范形式是一种确定性的默认表示，便于需要固定字符串的场合。

规范保证的唯一性是数值唯一：任何合法形式都必须解析为同一个精确数值，而不是要求所有实现输出同一个字符串。

6 进位

规范形式中的进位关系如下：

在规范形式中，必须按此表完成全部可进位。展示形式不受此限制。

以下示例假定扩展单位已支持：

7 数值范围

本规范表示的最大时长为 2^63−1 纳秒，约为 292 年。

• 实现必须支持 0 到最大值的完整范围。
• 总时长超过最大值的表示不是合法形式，解析必须失败。
• 不得回绕、截断或饱和。

8 解析与校验

• 解析合法形式必须得到精确的总时长。
• 需要确定字符串表示时，应生成规范形式。
• 比较必须按总时长进行，不得按字符串进行。
• 实现可以提供严格校验；严格校验只接受规范形式，其他输入必须失败。
• 大小写混写、空格分隔、µs、中文长写等不属于合法形式。

9 失败情形

以下情形用于区分解析失败的原因：

10 展示

规范保证解析结果数值唯一，展示可以优先人类阅读。

• 实现可以自行选择合适的单位展示。例如，在习惯以天读数的场景中，30d 比 4w2d 更易读；在习惯以秒读数的场景中，90s 比 1m30s 更易读。
• 本规范不规定展示形式的选择规则，也不要求展示形式与规范形式一致。
• 展示形式必须是合法形式。
• 同一时长的不同展示形式必须解析为同一数值。
• 展示形式不改变语法或数值语义。

11 与其他格式的关系

本节为定位说明，不构成规范要求。

• 需要与外部系统交换标准时长数据时，应使用 ISO 8601。
• 本格式坚持整数，以保证精确；需要更细粒度时，使用扩展单位。
• 本格式只表示非负时长；负值表达方向，不属于时长本身。
• 不支持小数，是因为有限小数不一定能在有限精度内精确表示，会引入舍入和数值歧义。

12 持续时间而非时间点

紧凑时长格式表示持续时间，而不是时间点。3d12h 表示一个持续 3 天 12 小时的长度，不表示 2026-11-08 12:00 这样的时刻。时间点应使用独立的 Date-Time 或 Timestamp 格式。

把一个持续时长加到某个时间点上属于日历运算，涉及时区、夏令时和月份边界等规则，应另行定义。本格式只定义固定长度时长本身。

13 一致性测试向量

下表可用于验证解析和规范化的行为：

• 第 1 至 9 行、第 13 至 14 行：核心单位，所有实现必须通过；
• 第 10 至 12 行：扩展单位，仅支持对应扩展单位的实现需要通过；
• 第 15 至 26 行：失败情形与严格校验，提供严格校验的实现需要通过。

14 从 1.0 到 2.0 的变更

15 参考引用

• RFC 2119：https://www.rfc-editor.org/rfc/rfc2119（规范性用语定义）
• ISO 8601：https://en.wikipedia.org/wiki/ISO_8601（日期与时间表示的国际标准）
• Go time.ParseDuration：https://pkg.go.dev/time#ParseDuration（Go 标准库的时长解析）
• 紧凑时长格式 1.0：https://srs.pub/thinking/compact-duration.html（上一版规范）