Go time.ParseDuration 的小数和负号怎么读：单位组合、溢出与错误处理

配置文件里写了 1.5h，程序却把它当成“只能填整数小时”；再遇到 -250ms 或 2h45m，校验代码就开始分叉。Go 的 time.ParseDuration 已经把这些情况统一处理好了，关键是理解它支持的语法、错误边界和 time.Duration 的纳秒范围。

ParseDuration 支持带符号的小数和连续单位；解析成功后得到纳秒精度的 time.Duration，解析失败或结果溢出时必须先处理 error，不能直接使用返回值。

先做一个可复现的解析实验

准备 Go 环境后，先把输入和结果同时打印出来。这个小程序故意把合法、负数、连续单位、非法单位和溢出输入放在一起，便于观察差异。

package main

import (
    "fmt"
    "time"
)

func main() {
    samples := []string{"1.5h", "-250ms", "2h45m", "1us", "3d", "1000000000000h"}
    for _, text := range samples {
        d, err := time.ParseDuration(text)
        if err != nil {
            fmt.Printf("%-18s error=%v\n", text, err)
            continue
        }
        fmt.Printf("%-18s duration=%s ns=%d\n", text, d, d.Nanoseconds())
    }
}

运行后，前三个输入和 1us 会得到时长；3d 会因为不支持 d 单位而失败，过大的小时数会触发范围错误。示例中的 1us 是文档明确接受的微秒写法，显示结果通常会规范化为 1µs。

小数、负号和连续单位分别怎么解释

解析器处理的是一个“数字 + 单位”的序列，而不是把字符串先转成浮点数再乘单位。这样做可以保留纳秒精度，也能在最后一步检测总和是否超出 Duration。

小数跟在数字后面

1.5h 等于 1 小时 30 分钟，0.000000001s 等于 1 纳秒。小数只能出现在数字部分，单位仍然必须紧跟在后面；1.5 h、1hour 都不是合法输入。

负号作用于整个时长

-1.5h 表示负一小时三十分钟。不要把它拆成“负号 + 正数”后再对每一段分别取反，业务层只需要把完整字符串交给 ParseDuration，再根据场景判断负值是否允许。

连续单位先分别换算再累加

2h45m10.5s 会依次换算成小时、分钟和秒，再合并为一个 Duration。这种写法适合人读的配置，但输入来自用户时仍应限制总长度，避免把错误文本当作可接受配置。

解析成功和失败的真实分支

下面的逻辑图对应本节的代码关系：输入进入 ParseDuration 后，成功路径得到 Duration，失败路径保留 error，调用方不能跳过这个分支。

func parseTimeout(raw string) (time.Duration, error) {
    d, err := time.ParseDuration(raw)
    if err != nil {
        return 0, fmt.Errorf("invalid timeout %q: %w", raw, err)
    }
    if d 

这里有两个不同层次的失败：字符串语法或范围不合法时，ParseDuration 返回 error；字符串合法但业务不接受负时长时，调用方再增加业务校验。把二者混成一个“解析失败”会让配置错误难以定位。

用边界实验验证单位和溢出

把输入分成四组测试，比只测试一个 10s 更可靠。尤其要覆盖最小纳秒、微秒别名、负数和超范围值。

func check(raw string) {
    d, err := time.ParseDuration(raw)
    switch {
    case err != nil:
        fmt.Printf("reject %-20s %v\n", raw, err)
    case d 

建议至少加入 1ns、1us、1µs、-1ms、2h45m、3d 和一个明显超过范围的小时数。可见的验收状态是：合法输入进入 accept，负值进入 negative，非法单位与溢出进入 reject。

配置场景里别踩这几个坑

不要忽略 error

直接写 d, _ := time.ParseDuration(raw) 会把拼写错误静默变成零值，服务可能以错误超时时间启动。启动阶段更适合返回带原始输入的错误，让配置中心或日志能直接定位字段。

不要自行用 float64 累加时长

先把小时转成浮点秒再乘纳秒，容易引入舍入误差。字符串时长交给标准库解析，最终用 Duration 做比较和传参。

不要把日和周当成内置单位

ParseDuration 没有 d、w 单位。日历上的“1天”可能涉及夏令时，而 Duration 是固定纳秒长度；如果业务需要自然日，应另行使用日期和时区模型。

相关问题

1h30m 和 90m 哪个更好？

两者都合法。面向人编辑的配置通常保留 1h30m 更直观，程序内部比较时它们都会变成同一个 Duration。

能不能用大写的 MS 或 H？

不能。单位是区分大小写的固定后缀，应在输入校验阶段给出原始字符串和允许单位提示。

负时长什么时候有用？

标准库允许负值，但超时、重试间隔、缓存 TTL 等配置通常不应接受负值；是否拒绝要由业务语义决定。

怎样确认结果没有溢出？

检查返回的 error。解析器会对超出 time.Duration 纳秒范围的输入返回错误，不要只看返回值是否为零。

把规则收进一条校验路径

如果字段代表超时或间隔，推荐固定成“解析、业务范围、带上下文返回”的顺序。标准库负责语法和数值范围，应用负责最小值、最大值和是否允许负值。这样一来，1.5h 这种合法小数不会被误拒绝，3d 和超大时长也能在启动前清楚失败。