Go time.ParseDuration 怎样处理配置里的时间字符串

配置里写 500ms、2s 或 1m30s 时，不能直接用 strconv.Atoi 读取。Go 标准库的 time.ParseDuration 会把带单位的字符串解析成 time.Duration，并通过 error 告诉我们格式、单位或数值范围是否有问题。

一、先固定 ParseDuration 接受的字符串边界

ParseDuration 接受一串带单位的十进制数字，每一段可以有小数，也可以带正负号。常见写法是 300ms、1.5h、2h45m。它表达的是经过的时长，不是带年月日的日历时间。

单位表可以先记成下面这组：ns 纳秒、us 或 µs 微秒、ms 毫秒、s 秒、m 分钟、h 小时。这里没有 d 或 w，因为天和周会受到日历与时区语义影响，不能简单等同于固定时长。

二、把配置读取与 Duration 解析分开

先拿到原始配置，再把解析动作集中到一个小函数里。这样环境变量、命令行参数和文件配置可以共用同一套错误语义，调用方也不会忘记检查返回的错误。

package config

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

// ParseDurationValue 统一解析配置时长，并把配置键名放进错误信息。
func ParseDurationValue(key, raw string) (time.Duration, error) {
    value := strings.TrimSpace(raw)
    if value == "" {
        return 0, fmt.Errorf("配置 %s 不能为空", key)
    }

    duration, err := time.ParseDuration(value)
    if err != nil {
        // 保留原始值，便于启动日志直接定位是哪一项配置写错。
        return 0, fmt.Errorf("配置 %s=%q 不是有效时长: %w", key, raw, err)
    }
    return duration, nil
}

这个函数没有把 500 猜成毫秒，也没有把错误值改成 0。时间单位是配置契约的一部分，缺少单位时宁可在启动阶段失败，也不要让请求超时策略悄悄改变。

三、处理空值、非法单位与负数

空值通常有两种语义：字段必填，或者使用业务约定的默认值。两者都应在配置层明确表达。非法单位如 10seconds、1d 会返回错误；负数在语法上可以存在，但是否允许要由使用场景判断。

package config

import (
    "fmt"
    "time"
)

// LoadTimeout 读取超时配置；空值使用默认值，但负数仍然拒绝。
func LoadTimeout(raw string) (time.Duration, error) {
    if raw == "" {
        return 5 * time.Second, nil
    }

    value, err := ParseDurationValue("REQUEST_TIMEOUT", raw)
    if err != nil {
        return 0, err
    }
    if value 

注意，0 和负数不是一回事。0s 是否代表“立即超时”“关闭超时”还是“不启用该功能”，都应由业务层单独约定；解析函数只负责把字符串转换成 Duration。

四、检查大数和配置边界

time.Duration 本质上是纳秒数，表示范围有限。输入过大、片段溢出或拼接后的总值超出范围时，ParseDuration 会返回错误。不要只取第一个返回值，也不要先把文本转成浮点数再乘单位，这两种写法都会让错误边界变得模糊。

五、在启动入口集中校验并输出可定位信息

服务启动时一次性读取所有时长配置，错误带上键名和原始文本；这样应用不会在收到第一条请求后才暴露配置问题。

package main

import (
    "fmt"
    "os"
)

// main 在服务启动前完成配置解析，避免错误延迟到运行期。
func main() {
    timeout, err := LoadTimeout(os.Getenv("REQUEST_TIMEOUT"))
    if err != nil {
        // 启动失败信息应包含配置名，便于定位部署环境的实际值。
        panic(err)
    }
    fmt.Printf("request timeout: %s\n", timeout)
}

如果配置来自更大的结构体，可以把多个键逐项解析后汇总错误；不要在每个业务调用点重复解析同一字符串。解析完成后，后续代码只接收 time.Duration，不再携带单位字符串到处流转。

常见问题

为什么 time.ParseDuration("30") 会失败？

因为裸数字没有单位。配置格式应明确写成 30s、30ms 等，避免不同服务对同一个数字作出不同猜测。

能不能把 1d 转成 24 小时？

如果业务明确规定“天就是固定的 24 小时”，可以在业务层单独扩展输入格式；不要把 1d 直接当成 ParseDuration 的合法输入。

负数一定是错误吗？

不一定。ParseDuration 可以表达负时长，但等待、超时和重试间隔通常不接受负数，应由对应配置加载函数根据业务语义拒绝。

总结

处理 Go 时间配置时，先把字符串契约限定在 time.ParseDuration 支持的单位内，再分离读取、解析和业务校验。统一检查 error、显式处理空值与负数，并在启动阶段保留键名和原始值，能够让配置错误更早、更容易定位。