登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go教程

Go time.Duration.String 怎样格式化耗时并处理零值

来源:17golang原创

时间:2026-11-17 06:43:11 211浏览 收藏

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。

time.Duration.String 对零值、纳秒、微秒、毫秒和秒选择展示单位的静态规则图
图1:Duration.String 对亚秒值的单位选择与零值分支,属于静态规则说明图,不是运行截图。
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。这适合表达时间差方向,但如果业务语义是“耗时”,通常应先确认为什么会得到负值,而不是直接把负号隐藏掉。

time.Duration.String 组合小时分钟秒并保留负号的静态关系图
图2:复合 Duration 的单位组合、负号保留和前导零单位省略,属于静态输出规则说明图,不是运行结果。
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()数值结果
把配置文本转成 Durationtime.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.Nanosecond1ns小于 1 微秒使用纳秒
1500*time.Microsecond1.5ms自动提升到更合适的单位
500*time.Millisecond500ms不会强制写成 0.5s
1*time.Hour + 2*time.Minute1h2m0s小时、分钟和秒按组合形式展示
-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 按业务协议指定小数位。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>