1 前言
在工程实践中，持续时间（Duration）几乎无处不在：连接的超时时间、缓存的有效期、重试的间隔、Token 的过期时间，以及日志里随处可见的执行耗时。但是如何表示一个持续时间，长期以来都没有一个让人省心的统一方案。
最常见的做法，是纯数字加一个隐含的单位。比如配置里写 timeout: 3600，你必须去翻文档，才能确认它的单位到底是秒还是毫秒；ttl: 86400 这种数字，不心算一下，几乎没有人能立刻反应过来是一天。数字一大，可读性就直线下降，换算出错更是家常便饭，把毫秒当成秒用造成的生产事故并不罕见。
另一种做法是自由文本，比如 2小时30分、2 hours 30 mins。这种写法人读起来是舒服了，但是机器没法统一解析：中英文混杂、全角半角、单词单复数，组合出来的写法千变万化，作为规范基本上不可用。
其实也有现成的国际标准，就是 ISO 8601 的 Duration，比如 P3W2DT1H20M33S。它足够标准，也足够严谨，但是对人工的书写和阅读并不友好：开头的 P，日期和时间之间的 T，都需要专门记忆，而且大小写敏感，稍长一点就容易写错。在工程配置、日志、状态描述这类高频读写的场合，它的冗长就成了实实在在的负担。
为了解决上面的问题，三恒移俗提出一种简洁、明确、机器可解析、人类可直读的时长表示法，即紧凑时长格式（Compact Duration Format）。
2 紧凑时长格式定义
紧凑时长格式用于以简洁、可读且确定的方式表示一个持续时间。它由一个或多个”数值 + 时间单位”组成，例如：
3w2d1h20m33s表示 3 周、2 天、1 小时、20 分钟、33 秒。
语法上可以简单的描述为：
Duration = TimeUnit+
TimeUnit = Number Unit其中：
Number：非负整数；Unit：规定的时间单位；- 各时间单元之间不得包含空格。
比如 30s、5m30s、2h15m、3d12h，都是合法的写法。
基础的时间单位一共五个：
| 单位 | 含义 | 换算关系 |
|---|---|---|
w |
周 | 7d |
d |
天 | 24h |
h |
小时 | 60m |
m |
分钟 | 60s |
s |
秒 | 基础单位 |
如系统需要更高的精度，可以向下扩展：
| 单位 | 含义 |
|---|---|
ms |
毫秒 |
us |
微秒 |
ns |
纳秒 |
扩展单位应在具体规范中明确启用范围，不应默认认为所有实现均支持。
需要说明的是，紧凑时长格式属于项目定义的时长表示法，不宣称与 ISO 8601 或其他国际标准在语法上兼容。它优先考虑的，是工程配置、日志、状态描述及人工阅读的简洁性。
3 规则说明
3.1 单位顺序
多个时间单位同时出现时，应按照时间尺度由大到小排列：
w → d → h → m → s → ms → us → ns例如 3w2d1h20m33s。推荐写 2h30m，不推荐写 30m2h。单位顺序固定之后，整个格式就不再需要任何分隔符，这也是”紧凑”二字的由来。
3.2 零值
单个时间单位的数值允许为 0，但在规范化表示中，应省略值为 0 的单位。例如 2h0m30s 应规范化为 2h30s。零时长表示为 0s。
3.3 规范化要求
对于同一个持续时间，应优先使用规范化表示：
- 单位按照从大到小排列；
- 相邻单位之间不重复；
- 能够进位的单位应进行进位；
- 省略值为
0的单位； - 必须至少包含一个时间单位。
例如 60s 规范化为 1m，90m 规范化为 1h30m。
3.4 不适用的时间单位
月份（month）和年份（year）不属于本格式的固定时长单位。原因是月份长度并不固定，年份长度可能是 365 或 366 天，因此无法将 1mo 或 1y 无歧义地换算为固定的秒数。像 1y2mo 这样的写法，不应作为紧凑时长格式使用。
如果业务需要表达”日历周期”，应另行定义 Calendar Period（日历周期），与固定时长区分开，而不是混在同一个格式里。
3.5 持续时间，而非时间点
紧凑时长格式表示的是持续时间，而非时间点。3d12h 表示一个持续 3 天 12 小时的时间长度，它不表示 2026-09-14 12:00 这样的时刻。时间点应使用独立的 Date-Time / Timestamp 格式表示。
4 示例
4.1 合法
0s
30s
5m
5m30s
2h
2h15m
3d
3d12h
2w3d4h20m33s
500ms
1s500ms4.2 非规范
2h 30m // 包含空格
30m2h // 单位顺序错误
2hours30min // 不使用规定单位
1y2mo // 不支持日历单位5 与 ISO 8601 的关系
紧凑时长格式是一种项目级规范，与 ISO 8601 Duration 等标准在语义上具有对应关系，但语法并不相同。例如：
3w2d1h20m33s对应 ISO 8601 的：
P3W2DT1H20M33S两者均表示持续时间。区别在于，ISO 8601 追求的是日历层面各种时间表示的完整覆盖，而本规范优先考虑工程配置、日志、状态描述及人工阅读的简洁性。因此，在与外部系统交换标准时长数据的场合，应使用 ISO 8601；在项目内部的配置与日志中，则推荐使用紧凑时长格式。
6 参考引用
- https://en.wikipedia.org/wiki/ISO_8601