Go 超时配置写成整数为什么只等了几纳秒

Go 里把超时写成 timeout := 5，再传给需要 time.Duration 的函数时，实际含义通常是 5 纳秒，不是 5 秒。因为 time.Duration 的内部单位就是纳秒，整数不会根据变量名或参数场景自动补上“秒”。固定值要写成 5 * time.Second；如果来自配置，更推荐保存带单位的字符串并用 time.ParseDuration 解析。

先看单位，再看数值：time.Duration(5) 等于 5ns，time.Duration(5) * time.Second 才等于 5s。

整数为什么会变成几纳秒

time.Duration 是一个以纳秒计数的整数类型。它的设计重点是让时间运算可以直接参与加减乘除，而不是替调用者猜测单位：

package main

import (
    "fmt"
    "time"
)

func main() {
    raw := 5
    short := time.Duration(raw)
    normal := time.Duration(raw) * time.Second

    fmt.Println(short)  // 5ns
    fmt.Println(normal) // 5s
}

因此下面这种写法很容易造成“超时配置不生效”的错觉：

timeout := 5
select {
case 

这里的定时器等待的是 5ns，调度和系统计时分辨率还会让实际表现受到运行环境影响，但它绝不会被解释成 5 秒。真正的错误在单位转换，而不在 time.After。

固定超时用单位常量表达意图

代码中的固定时间不要先写裸整数再强制转换，而应让单位出现在表达式里。这样审查代码时一眼就能看出接口等待的是秒还是毫秒：

const (
    connectTimeout = 3 * time.Second
    retryInterval  = 200 * time.Millisecond
    pollInterval   = 500 * time.Microsecond
)

变量是整数时，也要把“数值”和“单位”分开表达：

seconds := 5
timeout := time.Duration(seconds) * time.Second

milliseconds := 250
shortTimeout := time.Duration(milliseconds) * time.Millisecond

这里的乘法不是装饰。time.Second 本身就是一个表示一秒的 Duration 常量，乘法才完成从“多少个单位”到“多少纳秒”的换算。

配置值应该选整数单位还是带单位字符串

如果配置来源是环境变量、YAML 或 JSON，推荐直接约定 "5s"、"250ms"、"1m30s" 这样的文本。它能把单位一起保存，避免配置文档和代码各自猜测：

func readTimeout(value string) (time.Duration, error) {
    d, err := time.ParseDuration(value)
    if err != nil {
        return 0, fmt.Errorf("invalid timeout %q: %w", value, err)
    }
    if d 

ParseDuration 支持 ns、us/µs、ms、s、m 和 h。如果历史配置已经规定“整数表示毫秒”，也可以保留整数接口，但应在配置入口完成一次明确转换，后面的业务函数只接收 time.Duration。

用一张表排查超时过短和过长

排查时先打印最终的 Duration，不要只打印原始整数：

fmt.Printf("timeout=%s (%d ns)\n", timeout, timeout.Nanoseconds())

同时检查三件事：配置文档写的单位是否和解析代码一致；是否在入口处只转换了一次；乘法结果是否超出 Duration 可表示范围。对网络请求、重试和轮询这类参数，建议给零值、负值和异常大值设置明确的拒绝或回退策略。

相关问题

time.Duration(1) 能不能表示 1 秒？

不能。它表示 1 纳秒。表示 1 秒应使用 time.Second，或把秒数乘以 time.Second。

为什么不直接把配置字段声明成 time.Duration？

如果配置解码器支持带单位文本，可以直接使用；否则仍要明确输入是纳秒、毫秒还是秒。类型名不会替外部格式补单位。

超时应该写成 5s 还是 5000ms？

两者解析后的时长相同。团队配置优先选择可读、粒度足够且格式统一的一种写法，并在入口处校验范围。

参考：Go time 包文档、Go time 源码。