当前位置:首页 > 文章列表 > Golang > Go教程 > Go time.Duration.String 怎样格式化耗时并处理零值

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

来源:17golang原创 2026-11-17 06:43:11 0浏览 收藏

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删除
Go slog.Record.AddAttrs 怎样批量追加结构化日志字段Go slog.Record.AddAttrs 怎样批量追加结构化日志字段
上一篇
Go slog.Record.AddAttrs 怎样批量追加结构化日志字段
Go net/url.PathEscape 怎样只编码路径片段而不影响层级斜杠
下一篇
Go net/url.PathEscape 怎样只编码路径片段而不影响层级斜杠
查看更多
最新文章
查看更多
课程推荐
  • 前端进阶之JavaScript设计模式
    前端进阶之JavaScript设计模式
    设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
    543次学习
  • GO语言核心编程课程
    GO语言核心编程课程
    本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
    516次学习
  • 简单聊聊mysql8与网络通信
    简单聊聊mysql8与网络通信
    如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
    500次学习
  • JavaScript正则表达式基础与实战
    JavaScript正则表达式基础与实战
    在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
    487次学习
  • 从零制作响应式网站—Grid布局
    从零制作响应式网站—Grid布局
    本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
    485次学习
查看更多
AI推荐
  • PubMedQA数据集详解:生物医学问答基准、功能与应用指南
    PubMedQA
    深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
    1061次使用
  • H2O EvalGPT:开源LLM大模型评估与排行榜工具
    H2O EvalGPT
    H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
    1061次使用
  • LMArena是什么?伯克利AI模型评估平台使用指南与功能解析
    LMArena
    LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
    1227次使用
  • 斯坦福HELM:大语言模型Holistic Evaluation整体评估框架详解
    HELM
    深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
    1171次使用
  • MMBench详解:多模态大模型基准测试、功能特点与使用指南
    MMBench
    MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
    1013次使用
微信登录更方便
  • 密码登录
  • 注册账号
登录即同意 用户协议 和 隐私政策
返回登录
  • 重置密码