Go time.ParseDuration 读取配置时长的错误处理

配置里的超时时长通常是字符串，例如 750ms、2s 或 1m30s。Go 不应把它直接当整数秒处理，而应使用 time.ParseDuration 解析，再对空值、负值和业务上限做第二层判断。这样单位由配置表达，错误也能在启动阶段暴露。

先把配置时长当成带单位的值

time.Duration 本质上是纳秒计数，但配置层不应该让读者心算纳秒。官方定义的字符串由可带符号的十进制数和单位组成，可以组合成 2h45m，也可以写小数；微秒既可写 us，也可写 µs。相反，30、30sec 和 1d 都不能直接交给它。

这也是直接调用解析函数的最小写法：

package main

import (
    "fmt"
    "time"
)

func main() {
    raw := "750ms"
    d, err := time.ParseDuration(raw)
    if err != nil {
        // 语法错误必须被保留，不能把错误值当成零时长继续运行。
        fmt.Printf("duration %q is invalid: %v\n", raw, err)
        return
    }
    // Duration 可以直接传给定时器、context.WithTimeout 等 API。
    fmt.Println(d)
}

空值默认，非空值严格解析

默认值和非法值是两种不同情况。环境变量没有设置时，可以采用产品明确规定的默认值；一旦用户写了内容，即使拼写错误，也应该返回错误。下面的函数只负责读取一个配置项，默认值由调用方传入，避免把业务默认值散落在工具函数里。

package config

import (
    "fmt"
    "strings"
    "time"
)

func parseDuration(key, raw string, fallback time.Duration) (time.Duration, error) {
    value := strings.TrimSpace(raw)
    if value == "" {
        // 未配置与配置错误不同：未配置才使用调用方给出的默认值。
        return fallback, nil
    }

    d, err := time.ParseDuration(value)
    if err != nil {
        // 错误带上键名和原值，启动日志才能定位是哪项配置出错。
        return 0, fmt.Errorf("%s=%q: parse duration: %w", key, raw, err)
    }
    return d, nil
}

如果配置文件把空格当成有意义的输入，就不要擅自 TrimSpace；对常见环境变量场景，去除首尾空格通常能避免复制粘贴造成的误报。无论是否清理空格，都应在配置契约中写清楚。

解析成功后还要限制业务范围

ParseDuration 只判断格式能否转换成 Duration，不会知道某项配置是否允许负数，也不会替你决定最长超时时间。比如轮询间隔必须大于零，HTTP 超时可能要求不超过两分钟；这些属于应用规则，应在解析后单独检查。

package config

import (
    "fmt"
    "time"
)

func validateTimeout(key, raw string) (time.Duration, error) {
    d, err := parseDuration(key, raw, 5*time.Second)
    if err != nil {
        return 0, err
    }
    if d  2*time.Minute {
        // 上限用于防止配置误写后让请求长期占用资源。
        return 0, fmt.Errorf("%s must not exceed 2m", key)
    }
    return d, nil
}

启动阶段把错误交给调用方

不要在 validateTimeout 内部打印日志后返回一个猜测值。配置加载层更适合把错误向上返回，由启动入口统一决定退出、提示或进入受控的降级流程。下面的表格可以作为配置文档和测试用例的共同依据。

测试至少覆盖一条合法组合、一条空值、一条缺少单位、一条负数和一条超过上限的值。尤其不要只断言 err == nil：还要断言最终的 Duration，否则默认值分支可能悄悄失效。

相关问题

Go 的 ParseDuration 支持“天”吗？

不支持 d 单位。需要一天时可明确写成 24h，并在配置说明里解释这个约定。

配置写成 30 时能当作 30 秒吗？

不能直接这样推断。裸数字缺少单位会解析失败；如果产品确实规定整数代表秒，应先用专门的整数解析逻辑，并把该规则写进配置契约。

负时长一定是错误吗？

不一定是解析错误，但大多数超时、间隔和重试配置不接受负值。先让 ParseDuration 负责语法，再由具体配置项决定范围。