Go 中的 time.Duration 本质上是以纳秒计数的 int64,但日志里通常不希望看到一串很长的整数。直接调用 d.String(),就能把它转换为适合阅读的文本:较长耗时按小时、分钟和秒组合,亚秒值自动选择 ms、µs 或 ns,零值固定显示为 0s。
官方地址:https://pkg.go.dev/time#Duration.String
String() 负责“人类可读的展示”,不是固定宽度格式化器。它会省略前导零单位,也不会为了对齐日志而自动补齐位数。
先用 String 把耗时变成可读文本
最小用法是在得到 time.Duration 后调用 String()。下面的示例覆盖整小时、复合单位、毫秒和零值,代码中的注释说明每组输入想观察的边界。
package main
import (
"fmt"
"time"
)
func main() {
values := []time.Duration{
2 * time.Hour,
1*time.Hour + 2*time.Minute + 300*time.Millisecond,
300 * time.Millisecond,
0,
}
for _, value := range values {
// String 返回适合日志和提示文本阅读的单位组合。
fmt.Println(value.String())
}
}
这些输入对应的展示形式分别是 2h0m0s、1h2m0.3s、300ms 和 0s。可以看到,结果保留了非零的高阶单位,但不会把小时或分钟单独补成固定宽度。
亚秒耗时会自动选择更小单位
官方文档对亚秒值有一个实用规则:如果耗时小于 1 秒,String() 会选择更小单位,让结果的首位不是零。因此 500*time.Millisecond 显示为 500ms,而不是 0.5s;1500*time.Microsecond 会显示为 1.5ms。
package main
import (
"fmt"
"time"
)
func main() {
values := []time.Duration{
0,
1 * time.Nanosecond,
1500 * time.Microsecond,
500 * time.Millisecond,
1200 * time.Millisecond,
}
for _, value := range values {
// 用 %q 保留单位字符,便于区分 µs 等输出。
fmt.Printf("%q -> %s\n", value, value.String())
}
}
这里有三个容易混淆的点:
0不是空字符串,而是明确的0s。- 微秒单位使用微符号
µs;它不是字母us。 - 小数部分会去掉没有意义的尾部零,例如
1.500s不会保持三位小数。
复合耗时与负数怎样显示
当耗时跨越小时、分钟和秒时,String() 会把各单位组合起来。比如 1 小时、2 分钟和 300 毫秒会形成 1h2m0.3s。中间的 0s 不是多余信息:它表示秒这一位存在,但没有整数秒,仍有小数部分。
负数则保留负号,单位选择规则仍然相同。例如 -2500*time.Microsecond 表示为 -2.5ms。这适合表达时间差方向,但如果业务语义是“耗时”,通常应先确认为什么会得到负值,而不是直接把负号隐藏掉。
package main
import (
"fmt"
"time"
)
func main() {
values := []time.Duration{
1*time.Hour + 2*time.Minute + 300*time.Millisecond,
-2500 * time.Microsecond,
}
for _, value := range values {
// 负数会保留方向,不能把它当成无符号耗时处理。
fmt.Printf("duration=%s\n", value.String())
}
}
String() 省略的是前导零单位,不是任意零单位。例如 2*time.Hour 会是 2h0m0s,而不是 2h;这是为了保留标准 Duration 文本的结构。
String、Seconds 和 ParseDuration 不要混用
同一个 Duration 可以有不同用途的方法:
| 目标 | 适合的方法 | 结果 |
|---|---|---|
| 写日志、提示和诊断信息 | d.String() | 带单位的可读字符串 |
| 参与数值计算或指标上报 | d.Seconds()、d.Milliseconds() | 数值结果 |
| 把配置文本转成 Duration | time.ParseDuration(s) | (Duration, error) |
| 固定小数位或固定列宽 | fmt.Sprintf 配合数值方法 | 由业务自行控制格式 |
不要把 String() 的输出直接当成固定格式协议。它是标准化的可读表示,适合人看;如果下游系统要求固定单位、固定精度或纯数字,应明确选择数值方法,并由协议定义单位。
在耗时日志里保留原始值和可读值
在自动化任务、HTTP 请求或数据库操作的日志中,通常同时保留结构化的纳秒或毫秒数和一个可读字段。这样人可以快速阅读,指标系统也不会依赖字符串拆分。
package main
import (
"log/slog"
"time"
)
func logElapsed(logger *slog.Logger, started time.Time) {
elapsed := time.Since(started)
logger.Info("任务完成",
// String 供人阅读,Milliseconds 供聚合和阈值判断。
"elapsed", elapsed.String(),
"elapsed_ms", elapsed.Milliseconds(),
)
}
如果只需要给人看的单行文本,直接使用 elapsed.String() 即可;如果要做告警、排序或趋势图,应额外记录数值字段。不要让日志消费者解析 1h2m0.3s 来重新推导耗时。
速查:零值和常见输入怎么显示
| 输入 | 典型输出 | 要点 |
|---|---|---|
time.Duration(0) | 0s | 零值有明确单位 |
1*time.Nanosecond | 1ns | 小于 1 微秒使用纳秒 |
1500*time.Microsecond | 1.5ms | 自动提升到更合适的单位 |
500*time.Millisecond | 500ms | 不会强制写成 0.5s |
1*time.Hour + 2*time.Minute | 1h2m0s | 小时、分钟和秒按组合形式展示 |
-2500*time.Microsecond | -2.5ms | 负号表示方向仍被保留 |
小结
time.Duration.String() 的核心价值是把纳秒计数转换成稳定、易读的单位文本:零值是 0s,亚秒值会在 ns、µs、ms 和 s 之间选择,较长值会组合 h、m、s,负数保留负号。它适合日志和提示,不适合承担固定宽度协议或指标计算。
为什么 500ms 不显示为 0.5s?
因为 String 对小于 1 秒的值会优先选择能让首位非零的较小单位,所以 500 毫秒会显示为 500ms。
零值 Duration 能直接判断吗?
可以直接与 0 比较。调用 String() 时它会得到 0s,不会得到空字符串。
怎样让耗时固定保留三位小数?
不要依赖 String(),应先调用 Seconds() 或其他数值方法,再用 fmt.Sprintf 按业务协议指定小数位。