Go time.Duration 怎样安全转换毫秒参数

接口里的超时值常常以毫秒传入，但 Go 的 time.Duration 底层是纳秒计数。安全做法不是把任意整数直接乘上 time.Millisecond，而是在接口边界先解析，再校验负数和最大值，最后完成单位转换。这样得到的 Duration 才能放心交给 context.WithTimeout、定时器或 HTTP 客户端。

先分清毫秒参数与 Duration 的底层单位

标准库把 Nanosecond、Microsecond、Millisecond 等常量定义为 Duration。其中一毫秒等于一百万纳秒，Duration 本身是有符号的 int64 纳秒数。因此，转换的关键是把“外部整数毫秒”安全地映射到这个范围，而不是依赖编译器替你判断运行时溢出。

package main

import "time"

func basicDuration(ms int64) time.Duration {
	// 显式转换表示输入是毫秒，常量负责把单位换成纳秒。
	return time.Duration(ms) * time.Millisecond
}

这段写法只适合已经完成范围检查的值。运行时整数乘法溢出不会自动返回错误，结果可能绕回负数；如果输入来自请求、环境变量或配置文件，就不能把它当作校验方案。

用乘法前检查守住最大值边界

先解析字符串，再用除法得到可转换的最大毫秒数。除法检查不会产生乘法溢出，且把边界规则集中在一个函数里，调用方只需要处理返回的错误。

package timeout

import (
	"fmt"
	"strconv"
	"time"
)

const maxDuration = int64(1 maxMillis {
		return 0, fmt.Errorf("毫秒参数超出 Duration 范围")
	}
	return time.Duration(ms) * time.Millisecond, nil
}

如果业务允许“立即超时”，可以保留 0；如果必须有实际等待时间，再额外拒绝 ms == 0。不要把这两个规则混成类型转换规则，否则调用方很难判断是格式错误还是业务策略拒绝。

把参数检查放在接口边界

转换函数应该靠近 HTTP、RPC 或配置加载层。后续代码只接收 time.Duration，避免不同模块各自重复解析，也避免有人把已经是纳秒的值再次乘以毫秒常量。

测试边界值，避免只验证一个正常样例

最少覆盖正常值、零、负数、非法文本和最大值附近。对于上限测试，可以用 maxDuration / int64(time.Millisecond) 生成合法边界，再加一验证拒绝路径。这样测试跟随类型定义，不依赖手写的大数字。

func ExampleFromMillis() {
	// 正常值按毫秒解释，而负数和文本必须返回错误。
	d, _ := FromMillis("2500")
	fmt.Println(d == 2500*time.Millisecond)
	_, negativeErr := FromMillis("-1")
	_, textErr := FromMillis("2.5s")
	fmt.Println(negativeErr != nil, textErr != nil)
	// Output:
	// true
	// true true
}

结论很简单：外部毫秒值先解析、再按除法检查范围，最后才乘 time.Millisecond。把这条边界固定下来，后续无论接入定时器还是请求上下文，都不会因为一次异常输入把时间参数变成不可预测的负值。

常见问题

直接写 time.Duration(ms) * time.Millisecond 一定错误吗？

不是。对已证明在范围内的内部常量或受控值，它是正常写法；问题在于不能让它承担外部输入校验。

为什么不先乘再检查结果是否小于零？

溢出后的结果可能仍是正数，且检查已经发生在错误值产生之后。乘法前用最大值除以单位常量更可靠。

毫秒参数要不要改成 time.ParseDuration？

只有当接口协议明确接受 2500ms 或 2.5s 这类带单位文本时才适合。当前协议是纯整数毫秒，保持单一格式更容易校验和兼容。