time.ParseDuration
解析给定的时长字符串,返回 time.Duration 值。
这一页解决什么问题
把时长字符串("24h"、"2h45m"、"300ms"、"-1.5h")解析成 time.Duration,之后可以用 Duration 的方法算出秒数/分钟数。
职责划分很简单:字符串进来 → time.ParseDuration;「数量 + 单位」两个值进来 → time.Duration。两者返回同一个类型。
什么时候用,什么时候别用
该用:
- 配置或前置元数据里写的是时长字符串(对写配置的人最友好);
- 需要把人类可读的时长转成可计算的 Duration。
别用:
- 手边是「数量 + 单位」(如
unit = "hour"、value = 24)→ 用time.Duration; - 想解析的是日期不是时长 → 用
time.AsTime; - 想算两个时间的间隔 → 直接相减,结果本来就是 Duration;
- 想表示「天」→ 时长单位里没有
d(实测报错),写成"24h"或"48h"。
用法
time.ParseDuration 函数返回一个 time.Duration 值,可与任意 Duration 方法配合使用。
时长字符串是可能带符号的十进制数序列,每个数可带小数部分与单位后缀,例如 300ms、-1.5h 或 2h45m。有效的时间单位为 ns、us(或 µs)、ms、s、m、h。
以下模板:
go-html-template
{{ $duration := time.ParseDuration "24h" }}
{{ printf "There are %.0f seconds in one day." $duration.Seconds }}渲染为:
There are 86400 seconds in one day.完整示例:几种常见时长字符串
layouts/_partials/parse-duration.htmlgo-html-template
{{ $d := time.ParseDuration "24h" }}
<p>{{ $d }}</p>
<p>秒:{{ $d.Seconds }}</p>
<p>组合单位:{{ time.ParseDuration "2h45m" }}</p>
<p>毫秒:{{ time.ParseDuration "300ms" }}</p>
<p>负数与小数:{{ time.ParseDuration "-1.5h" }}</p>
<p>零值:{{ time.ParseDuration "0s" }}</p>Hugo 渲染为:
html
<p>24h0m0s</p>
<p>秒:86400</p>
<p>组合单位:2h45m0s</p>
<p>毫秒:300ms</p>
<p>负数与小数:-1h30m0s</p>
<p>零值:0s</p>你应当看到什么:时长按规范形式输出(2h45m0s、-1h30m0s);多个单位可以连写;支持负数与小数;0s 是合法输入。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
合法字符串("24h"、"2h45m"、"300ms"、"-1.5h"、"0s") |
time.Duration |
否 |
缺少单位("24") |
—— | 是:error calling ParseDuration: time: missing unit in duration "24" |
空字符串 "" |
—— | 是:error calling ParseDuration: time: invalid duration "" |
不支持的单位("1d") |
—— | 是:time: unknown unit "d" in duration "1d"(没有「天」) |
输入是数字(如 42) |
—— | 是:time: missing unit in duration "42"(会先被当成字符串 "42" 解析) |
| 返回类型 | time.Duration(默认输出 24h0m0s 这种规范形式) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | missing unit in duration "24" |
数字没带单位 | 写成 "24h" |
| 报错看不懂 | unknown unit "d" |
用了「天」d(Go 的时长语法没有天) |
换算成小时:"24h" |
| 报错看不懂 | invalid duration "" |
配置项是空字符串 | 给配置项设默认值,或先用 with 判空 |
| 没报错但结果不对 | 秒数与预期差 60 倍 | 把 m(分钟)当成了毫秒 |
毫秒是 ms,分钟是 m |
更多排查入口见故障排查。