Go time.Duration 怎样避免毫秒和纳秒混用

Go 里最容易被忽略的时间问题，不是 API 不会用，而是一个看起来正常的整数被当成了错误单位。比如配置写着 500，代码直接执行 time.Duration(500)，传给定时器后实际只有 500 纳秒，结果就像“没有等待”一样。

官方文档地址：https://pkg.go.dev/time

处理这类问题的核心只有一句话：外部配置如果表示毫秒，就在进入业务层时明确乘以 time.Millisecond；进入业务层后统一使用 time.Duration，不要再让调用方猜单位。

先看清 time.Duration 的底层单位

time.Duration 本质上是一个带语义名称的整数类型，表示两个时间点之间的间隔，底层按纳秒计数。标准库把 time.Nanosecond 定义为 1，再由它构造出微秒、毫秒、秒和分钟等常量。

因此下面两个写法虽然都能通过编译，含义却完全不同：

package main

import (
	"fmt"
	"time"
)

func main() {
	// 裸整数转换后仍然按纳秒解释，不代表 500 毫秒。
	wrong := time.Duration(500)

	// 用单位常量表达意图，结果才是 500 毫秒。
	right := time.Duration(500) * time.Millisecond

	fmt.Println(wrong) // 按代码逻辑会显示 500ns
	fmt.Println(right) // 按代码逻辑会显示 500ms
}

特别要注意，time.After(500) 也可能被误读成 500 毫秒。这里的无类型常量会被转换成函数需要的 time.Duration，最终仍然是 500 纳秒。只要参数是裸数字，就应该先问一句：这个数字的单位在哪里表达？

毫秒配置要在入口处转换一次

如果配置文件约定超时时间是毫秒，推荐让配置结构体也保留这个事实，但在解析完成后马上转换。后续函数只接收 time.Duration，这样 time.NewTimer、time.After 和 context.WithTimeout 不需要重复解释单位。

package timeout

import (
	"errors"
	"time"
)

// ParseMillis 把外部的毫秒整数转换成业务层统一使用的 Duration。
func ParseMillis(ms int64) (time.Duration, error) {
	// 这里把 0 和负数视为配置错误，避免定时器立即触发或语义不清。
	if ms > 1)
	const maxMillis = maxInt64 / int64(time.Millisecond)
	if ms > maxMillis {
		return 0, errors.New("timeout is too large")
	}

	// 单位只在这一层补上，调用方拿到的值不再是裸数字。
	return time.Duration(ms) * time.Millisecond, nil
}

这个入口有三个作用：第一，代码读者能从函数名看出输入单位；第二，单位转换不会散落在多个调用点；第三，零值、负值和乘法溢出可以在离业务最近的地方被拒绝。

不要把已经是 Duration 的值再乘一次

最常见的第二类错误，是函数参数已经声明为 time.Duration，调用方却仍然按毫秒再次相乘。比如某个配置库已经把 500ms 解析成了 500*time.Millisecond，再写 value * time.Millisecond 就会把它放大很多数量级。

建议用命名让边界清楚：

package timeout

import (
	"fmt"
	"time"
)

type ServiceConfig struct {
	// Timeout 已经是 Duration，业务代码不需要猜测单位。
	Timeout time.Duration
}

func startTimer(cfg ServiceConfig) *time.Timer {
	// 这里直接传递 Duration，不能再次乘 time.Millisecond。
	return time.NewTimer(cfg.Timeout)
}

func parseTextDuration(raw string) (time.Duration, error) {
	// 字符串带有明确单位，例如 "500ms" 或 "2s"。
	if raw == "" {
		return 0, fmt.Errorf("duration is empty")
	}
	// ParseDuration 负责识别单位，调用方不再手工拆分数字和后缀。
	return time.ParseDuration(raw)
}

上面的代码片段如果放进独立文件，还需要为 fmt 增加导入；这里重点是接口边界：整数毫秒、已经转换的 Duration、带单位的字符串应该分别有清晰入口，不要用一个模糊的 interface{} 让调用者自行猜测。

定时器和超时参数怎样做最后一层检查

转换完成后，调用方只接收 time.Duration，但仍要决定零值和负值的业务含义。time.NewTimer 对非正时长会很快进入可触发状态；这不一定是错误，但如果业务期待“等待一段时间”，就应该在入口拒绝。对上下文超时也一样，超时为零常常意味着立即取消。

一套简单的检查表如下：

排查“定时器几乎立即触发”的顺序

遇到超时过短、轮询过快或重试间隔异常时，可以按下面的顺序定位：

1. 找到最外层配置的单位约定，确认数字究竟是毫秒、秒还是已经带单位的文本。
2. 沿着调用链查看第一次转换的位置，重点搜 time.Duration(value) 和 * time.Millisecond 是否成对出现。
3. 检查传入定时器的变量类型。变量如果已经是 time.Duration，后续应直接传递。
4. 日志使用 duration.String() 或直接打印 duration，观察结果是 500ns、500ms 还是 0s。
5. 最后检查零值、负值和极大值的策略，避免修复单位后又把边界输入带入生产调用。

总结一下：毫秒和纳秒混用的根因通常不是 time 包行为不稳定，而是单位没有随着数据一起表达。把毫秒转换集中在配置入口，把业务参数统一成 time.Duration，并在日志中打印带单位的结果，就能把这类问题变成普通的类型和边界检查。

常见延伸问题

为什么 time.Duration(1) 不是 1 秒？ 因为 Duration 的底层计数单位是纳秒，1 只表示 1 纳秒；应使用 time.Second 或带单位的乘法。

配置应该直接存毫秒还是存 500ms？ 两种都可以，但必须统一约定。整数适合固定协议字段，带单位字符串更直观；无论哪种，都应在边界处转换一次。

能不能把所有输入都定义成 int64？ 不建议。进入业务层后使用 time.Duration，能让函数签名携带时间语义，减少再次换算的机会。