Go time.Duration 怎么避免把整数误当成秒

Go 里最容易被忽略的时间单位错误，是把配置中的整数直接转成 time.Duration，然后以为它代表“几秒”。正确做法是先说清整数的单位，再乘以 time.Second、time.Millisecond 等常量；如果输入本身带单位，就交给 time.ParseDuration 解析。

一句话记忆：time.Duration(5) 只有 5 纳秒，5 * time.Second 才是 5 秒。裸整数永远不要让业务代码猜单位。

先记住：time.Duration 存的是纳秒，不是秒

time.Duration 是一个有名类型，本质上用 int64 保存纳秒数。它不是“自动理解秒”的整数容器，所以 time.Duration(5) 表示 5ns，而不是 5s。Go 的时间包预定义了 time.Second、time.Millisecond 等单位常量，应该用乘法把数字和单位绑在同一个表达式里。

package main

import (
	"fmt"
	"time"
)

func main() {
	// 裸整数转换后仍然是 5 纳秒，不会自动变成 5 秒。
	wrong := time.Duration(5)
	// 用单位常量表达业务意图，结果才是 5 秒。
	right := 5 * time.Second
	fmt.Println(wrong, right)
}

这两个值都能通过编译，危险之处正在于编译器不会替你判断“5”究竟是秒、毫秒还是纳秒。把单位写进表达式后，代码评审和后续修改才有明确依据。

把外部整数转换成明确单位

配置文件、命令行参数和接口字段常把时长写成整数。转换前先固定字段契约：字段名叫 timeoutSeconds 就按秒处理，叫 timeoutMilliseconds 就按毫秒处理；不要用一个名为 timeout 的整数让调用方猜。

package main

import (
	"fmt"
	"time"
)

func durationFromConfig(timeoutSeconds int, retryText string) (time.Duration, error) {
	// 秒数用 time.Second 绑定单位，避免被当成纳秒。
	if timeoutSeconds 

如果字段是毫秒，转换应明确写成 time.Duration(milliseconds) * time.Millisecond。如果输入可以由用户填写，推荐采用 "750ms"、"2s" 这样的带单位字符串，解析失败就拒绝配置，而不是默默使用默认值。

把单位检查放进超时和重试代码

得到 Duration 后再交给 context.WithTimeout、time.Sleep、time.NewTimer 或重试间隔。转换只做一次，后续变量名直接体现类型和语义：

package main

import (
	"context"
	"time"
)

func requestContext() (context.Context, context.CancelFunc) {
	// timeout 已经是带单位的 Duration，调用点不再重复换算。
	timeout := 800 * time.Millisecond
	ctx, cancel := context.WithTimeout(context.Background(), timeout)
	// retryDelay 表示间隔，实际调用方应负责调用 cancel。
	_ = 2 * time.Second
	return ctx, cancel
}

排查时重点看三处：整数从哪里来、单位在哪一行绑定、最终参数是否可能为零或负数。尤其不要在重试循环里反复执行 time.Duration(n) * time.Second，却让 n 同时承担“次数”和“秒数”两个含义。

常见误区与一份可复用写法

第一类误区是先除后转，例如把毫秒整数除以 1000 再转成 Duration，这会在不足一秒时直接截断；应先转成 Duration，再乘以对应单位。第二类误区是忽略整数范围，外部输入很大时要在转换前做范围检查。第三类误区是把 Duration.Seconds() 的浮点结果重新当作精确整数使用；展示和日志可以用它，业务比较更适合继续比较 Duration。

func parseTimeout(seconds int64) (time.Duration, error) {
	// 先检查业务范围，再绑定单位，避免异常值放大成超长等待。
	if seconds  300 {
		return 0, fmt.Errorf("timeout seconds out of range: %d", seconds)
	}
	return time.Duration(seconds) * time.Second, nil
}

// 比较时保留 Duration 类型，避免 Seconds() 的浮点转换参与判断。
if timeout >= 30*time.Second {
	// 这里处理较长超时策略。
}

相关问题

为什么 time.Duration(60) 不是一分钟？

因为 Duration 的数值单位是纳秒，60 只代表 60ns。要表达一分钟，应写成 time.Minute，或写成 60 * time.Second。

配置里写 1.5 秒应该怎么办？

优先把字段定义成字符串并写成 "1.5s"，交给 time.ParseDuration 返回带错误的 Duration；不要把小数秒先转成整数再乘单位。

参考：Go time 包中的 Duration 文档，其中说明了 Duration 的纳秒计数表示和 ParseDuration 支持的单位后缀。