Go time.Duration 统一超时配置单位

我在配置超时参数时最容易踩的坑，不是 context.WithTimeout 本身，而是配置文件里的 30 到底代表 30 秒、30 毫秒，还是被某一层当成纳秒。更稳妥的做法是：配置统一写成 500ms、2s 这类带单位字符串，进入 Go 程序后只在入口调用一次 time.ParseDuration，后续都传递 time.Duration。

先把超时配置写成带单位的字符串

time.Duration 是一个基于整数的时间长度类型，常用单位包括 ns、us、µs、ms、s、m 和 h。它在程序内部以纳秒表达，但这不意味着配置文件也应该填写纳秒整数。配置写成 2s，读者能直接知道含义；写成 2000000000，维护者必须先查约定。

因此，配置结构可以把超时保留为字符串，解析完成后再进入业务层：

type RawConfig struct {
    // 配置层保留单位文本，让 500ms 和 2s 自带语义。
    RequestTimeout string
}

type Config struct {
    // 业务层只接收已经解析过的时间长度。
    RequestTimeout time.Duration
}

图中的关键边界是“文本输入”和“Duration 值”分开。输入带单位，内部统一类型，业务代码就不需要猜测数字的来源。

在配置入口集中解析并校验范围

解析时不要把错误吞掉，也不要让不同模块各自实现一套“字符串转秒”的逻辑。可以把默认值和业务允许范围放在同一个入口，最后只返回一个可供业务使用的 time.Duration：

func parseTimeout(raw string) (time.Duration, error) {
    const (
        defaultTimeout = 2 * time.Second
        minTimeout     = 100 * time.Millisecond
        maxTimeout     = 30 * time.Second
    )

    if raw == "" {
        // 空配置使用明确的默认值，避免把空串交给业务层猜测。
        return defaultTimeout, nil
    }

    timeout, err := time.ParseDuration(raw)
    if err != nil {
        // 非法单位或格式必须返回错误，不能静默改成 0。
        return 0, fmt.Errorf("request timeout %q: %w", raw, err)
    }
    if timeout  maxTimeout {
        // 范围限制属于业务策略，防止配置导致立即超时或长期占用。
        return 0, fmt.Errorf("request timeout %s is outside [%s, %s]", timeout, minTimeout, maxTimeout)
    }
    return timeout, nil
}

使用这段代码时记得导入 fmt 和 time。这里的重点不是固定的 2 秒或 30 秒，而是把策略集中在配置入口；实际范围应按接口、任务类型和资源成本调整。1.5s、250ms 这类小数单位可以直接由解析器处理，30 这类没有单位的输入则应被当作格式错误。

一个 Duration 值服务多个超时消费者

解析结果进入业务层后，不要再先转成整数秒、再乘回纳秒。上下文、HTTP 客户端和 ticker 都可以直接接收 time.Duration，这样同一份配置在不同组件之间保持相同语义：

func newRuntime(cfg Config, client *http.Client) (context.CancelFunc, *time.Ticker) {
    ctx, cancel := context.WithTimeout(context.Background(), cfg.RequestTimeout)
    // HTTP Client 直接复用 Duration，避免重复做单位换算。
    client.Timeout = cfg.RequestTimeout
    // ticker 的周期也必须是正的、已经解析过的 Duration。
    ticker := time.NewTicker(cfg.RequestTimeout)
    // 调用方负责在生命周期结束时调用 cancel 和 ticker.Stop。
    _ = ctx
    return cancel, ticker
}

示例只展示类型关系，真实代码还要在任务结束时调用 cancel() 和 ticker.Stop()，并根据生命周期决定是否复用客户端。还要注意：请求上下文超时、HTTP 客户端总超时和周期任务间隔虽然都使用 Duration，但它们表达的是不同的业务边界，不能因为类型相同就强行共用一个配置项。

排查超时单位不一致的四个问题

最终可以记住一条边界：外部配置负责表达“多长时间”，解析层负责把它变成可信的 time.Duration，业务组件只消费已经校验过的值。这样改单位时只改配置，不必在每个调用点寻找隐藏的乘法和除法。

常见问题

time.Duration 配置直接写整数可以吗？

不建议。除非项目明确规定整数单位并由一个入口统一转换，否则整数缺少自解释能力，容易在不同模块间产生单位偏差。

time.ParseDuration("30") 会得到 30 秒吗？

不会。它要求输入带有时间单位，应该写成 30s；解析失败时应保留错误，不要把失败结果当作零超时。

所有超时都应该共用一个配置字段吗？

不应该。请求总超时、连接超时、重试间隔和后台任务周期的业务含义不同，可以统一使用 time.Duration 类型，但应分别命名、分别设置范围。