Go time.Duration 如何安全解析用户输入的毫秒和秒

如果配置里写的是“500毫秒”或“2秒”，不要先把字符串转成整数再乘常数。Go 更稳妥的做法是要求输入带单位，直接交给 time.ParseDuration 解析，再在业务层限制范围。这样 500ms 会得到半秒，2s 会得到两秒，而裸数字 500 会被拒绝，不会被悄悄猜成纳秒或秒。

一、先把毫秒和秒写成带单位的字符串

time.Duration 本质上是纳秒数，但这不意味着外部输入应该直接填写纳秒整数。对人可读的配置，推荐使用 500ms、2s、1.5s 或 1m30s。其中 ms 明确表示毫秒，s 明确表示秒，单位不会因调用方不同而漂移。

二、用 time.ParseDuration 解析，并把错误留在输入边界

解析函数返回两个值：成功时得到 time.Duration，失败时得到 error。不要忽略这个错误，也不要在失败后默认改成某个时长。下面的包装函数先去掉配置常见的首尾空白，再保留一个可读的错误上下文。

package durationinput

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

// ParseTimeout 只负责把带单位的文本解析成 Duration。
// 范围和正负值交给调用方决定，避免把通用解析器绑定到单一业务。
func ParseTimeout(raw string) (time.Duration, error) {
    value := strings.TrimSpace(raw)
    if value == "" {
        return 0, fmt.Errorf("duration is empty") // 空输入不能偷偷变成零超时
    }

    d, err := time.ParseDuration(value)
    if err != nil {
        return 0, fmt.Errorf("invalid duration %q: %w", value, err) // 保留原始解析错误
    }
    return d, nil
}

这个 API 接受 +2s、-500ms 和 2m30s 这样的语法，但是否允许它们是业务问题。ParseDuration 不接受“半秒”这类中文单位，也不接受没有单位的 2；调用方应该在文档和示例中固定一种输入约定。

三、解析成功后，再做超时场景的安全校验

对 HTTP 超时、重试间隔这类场景，负数和零通常没有业务意义，过大的值还可能让请求长期占用连接。可以把解析与策略校验分成两层：第一层只负责语法，第二层负责当前场景的最小值和最大值。

// ValidatePositiveTimeout 把通用 Duration 收紧为一个可用的超时范围。
func ValidatePositiveTimeout(raw string) (time.Duration, error) {
    d, err := ParseTimeout(raw)
    if err != nil {
        return 0, err // 先返回语法错误，调用方可定位配置字段
    }
    if d  maxTimeout {
        return 0, fmt.Errorf("duration must not exceed %s", maxTimeout)
    }
    return d, nil
}

如果场景是“允许立即返回”，可以把下限从 > 0 改成 >= 0；如果是退避等待，则还应单独决定是否接受负数。关键是不要把这些规则藏进一个对所有业务都适用的解析函数。

四、用边界表和测试确认单位没有错位

测试至少覆盖毫秒、秒、小数、组合单位、空白、裸数字和超范围值。特别要断言 500ms 等于 500*time.Millisecond，这样后续有人把输入转换逻辑改成整数时，测试能及时发现单位错误。

func ExampleValidatePositiveTimeout() {
    d, err := ValidatePositiveTimeout("500ms")
    if err != nil {
        panic(err) // 示例中直接终止，生产代码应返回或记录错误
    }
    fmt.Println(d == 500*time.Millisecond)
    // 输出：true，明确验证输入单位没有被换算错
    // Output: true
}

实际项目还可以把允许的最大值放进配置结构或常量，并在启动时一次性校验。不要在每次请求到来时才发现全局超时配置是空字符串，也不要用默认值掩盖拼写错误。

相关问题

为什么不能直接把“500”当成 500 毫秒？

因为裸数字没有稳定单位，而 time.Duration 的底层单位是纳秒。强制写 500ms 能让配置、人读文档和程序解析保持一致。

1.5s 和 1500ms 有区别吗？

两者都能表达 1.5 秒；选一种团队约定即可。短间隔配置通常用毫秒，面向等待时长的配置通常用秒，重点是始终保留单位。

解析成功后还需要判断最大值吗？

需要。解析器只判断语法和数值是否能表示，无法知道你的 HTTP、重试或任务调度场景允许等待多久，范围必须由业务层补充。