当前位置：首页 > 文章列表 > Golang > Go教程 > Go time.ParseDuration 的小数和负号怎么读：单位组合、溢出与错误处理

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

来源：17golang原创 2026-08-28 04:29:20 0浏览收藏

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

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

要点速览

1.5h、-250ms、2h45m 都是合法形式。
合法单位只有 ns、us/µs、ms、s、m、h。
结果落在 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，调用方不能跳过这个分支。

ParseDuration 将输入分为 Duration 成功结果和 error 失败分支的 Go 代码逻辑图

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。