Go time.Duration 解析用户输入时如何避免溢出：ParseDuration、范围校验与配置回退

服务启动时从环境变量读取超时时间，最容易踩的坑不是单位写错，而是把用户输入直接转成 time.Duration 后就拿去创建定时器。稳妥做法是先用 time.ParseDuration 解析，再检查错误和业务上限；超出上限时明确回退或拒绝，不能依赖整数转换“自然修正”。

time.Duration 是 int64 纳秒数，解析成功不代表符合业务范围。把“语法合法”和“允许使用”分成两次判断，才能挡住极大值、负数和空配置。

线上配置里，合法时长也可能是不合适的时长

假设服务允许配置 REQUEST_TIMEOUT。有人填了 30s，有人填了 0，也有人为了“先别超时”填了 9999999999h。这几种字符串的格式判断不能和业务决策混在一起。

官方定义中，Duration 以纳秒计数，底层类型是 int64，可表示范围大约 290 年。ParseDuration 识别的是带单位的数字序列，支持 ns、us、µs、ms、s、m、h，并不替你判断这个值是否适合接口超时。

先让 ParseDuration 处理语法，再单独判断范围

配置入口可以保持很小：输入为空时使用默认值；输入非空时解析；解析成功后再与 maxTimeout 比较。

func timeoutFromEnv(raw string) (time.Duration, error) {
    const defaultTimeout = 3 * time.Second
    const maxTimeout = 30 * time.Second

    if raw == "" {
        return defaultTimeout, nil
    }

    parsed, err := time.ParseDuration(raw)
    if err != nil {
        return 0, fmt.Errorf("invalid REQUEST_TIMEOUT %q: %w", raw, err)
    }
    if parsed  maxTimeout {
        return 0, fmt.Errorf("REQUEST_TIMEOUT must be between 1ns and %s", maxTimeout)
    }
    return parsed, nil
}

这里的 err 只表示字符串没有按时长语法解析成功；即使 err == nil，还必须检查 parsed。尤其不要先把字符串当普通整数读取再乘以单位，乘法可能在转换前就越界。

回退策略要区分空配置、坏配置和超范围配置

是否回退是产品策略，不是 ParseDuration 的职责。对开发环境可以回退到 defaultTimeout 并记录告警；对生产配置则更适合让启动失败，避免服务带着错误超时继续接收流量。

func timeoutOrDefault(raw string) time.Duration {
    const defaultTimeout = 3 * time.Second
    const maxTimeout = 30 * time.Second

    if raw == "" {
        return defaultTimeout
    }
    parsed, err := time.ParseDuration(raw)
    if err != nil || parsed  maxTimeout {
        return defaultTimeout
    }
    return parsed
}

这个版本适合明确允许“坏配置不阻断启动”的场景。实际项目里最好把回退与日志绑定，例如记录原始 raw、采用的 defaultTimeout 和拒绝原因，避免排查时只看到“超时变短了”。

测试时同时覆盖单位、负数和极大值

测试不要只放一个 10s。下面几组输入分别覆盖空值、合法单位、格式错误、负数和超过业务上限的时长：

如果还要验证整数边界，可以使用接近 time.Duration 最大值的小时数，但不要把某个机器上的内部容量或计时器实现当成测试契约。测试真正要锁定的是错误、范围和最终采用的配置。

常见问题：几个容易被忽略的边界

为什么解析成功后还要判断上限？

解析器只负责把字符串转换成时长值。一个几百年的时长可能在类型范围内，却会让 HTTP 请求、缓存刷新或重试任务长时间不返回。

零值一定是错误吗？

不一定。某些 API 用零表示“不设置超时”，但这必须是明确的业务约定；若接口需要保护下游，通常应把零值单独拒绝。

应该回退还是让服务启动失败？

影响安全边界的超时配置更适合启动失败并暴露错误；允许动态调整的内部工具可以回退，但必须留下日志和指标。关键是不要静默吞掉错误。

最后检查采用的值，而不是只检查字符串

这类配置的验收顺序很固定：确认空值策略，调用 time.ParseDuration，处理 err，检查 parsed 与 maxTimeout，最后记录实际生效的时长。这样即使输入单位、默认值或上限以后调整，代码仍然把语法解析和业务边界分开，问题会更容易定位。