Go time.Duration 转整数为什么会丢精度：单位常量与时间计算边界

监控配置里把 750*time.Millisecond 传给一个只接收整数秒的函数，日志却显示成了 0。问题不在计时器“变快了”，而在 time.Duration 先被换算成目标单位，再按整数规则截掉小数。只要把单位、返回类型和调用方的精度要求对齐，这类 bug 很容易稳定复现，也容易修好。

先把 time.Duration 当成带单位的接口类型

time.Duration 是一个有明确语义的整数类型，内部保存纳秒数。下面两个值打印出来都像数字，但它们表达的单位并不一样：

short := 750 * time.Millisecond
long := 750 * time.Second
fmt.Println(short, long)
// 750ms 12m30s

真正容易出错的是把它直接交给只接受 int 的旧接口。int(short) 得到的是纳秒数量，不是 0 秒，也不是 750 毫秒。这个转换只是换了静态类型，并没有发生单位换算。

整数转换丢精度，通常发生在两道门

第一道门是除法。如果两个操作数都是整数，结果仍然是整数：

func wholeSeconds(d time.Duration) int64 {
    return int64(d / time.Second)
}

fmt.Println(wholeSeconds(750 * time.Millisecond)) // 0
fmt.Println(wholeSeconds(1750 * time.Millisecond)) // 1

这不是四舍五入，而是向零截断。负数也一样，-1750ms / 1s 得到 -1。如果业务要“只要有剩余就算一个完整窗口”，应明确写出向上取整规则，不要让调用方猜。

第二道门是把浮点结果再转回整数：

d := 1750 * time.Millisecond
seconds := d.Seconds()       // 1.75
whole := int64(seconds)      // 1，仍然是截断
rounded := int64(seconds + 0.5) // 非负秒数可得到 2

最后一行只适用于已确认非负的数值。超时、延迟和剩余时间最好继续使用 Duration，只有在协议或存储字段明确要求整数时才在边界处转换。

从接口目标倒推参数设计

如果函数内部要调用 time.After、context.WithTimeout 或 Timer.Reset，接口就直接接受 time.Duration：

func waitForReply(ctx context.Context, timeout time.Duration) error {
    ctx, cancel := context.WithTimeout(ctx, timeout)
    defer cancel()
    // 业务请求放在这里，超时语义由调用方明确传入
    return nil
}

_ = waitForReply(context.Background(), 750*time.Millisecond)

如果对接外部协议必须传整数，建议在函数名或参数名中露出单位，例如 retryAfterSeconds int，并在入口集中换算。不要在业务深处散落 int64(d / time.Second)，否则同一个字段很快会出现秒、毫秒混用。

展示值和控制值不要共用一个整数

页面显示“1.75 秒”可以使用 d.Seconds()，控制超时则保留原始 Duration。把展示用的整数秒重新拿去做控制，会把 1750 毫秒缩短为 1 秒；把纳秒数直接展示，又会让读者看到难以理解的大整数。

一组小测试把边界锁住

func TestWholeSeconds(t *testing.T) {
    cases := []struct {
        name string
        in   time.Duration
        want int64
    }{
        {"below one second", 750 * time.Millisecond, 0},
        {"one second plus", 1750 * time.Millisecond, 1},
        {"exact boundary", 2 * time.Second, 2},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            if got := int64(tc.in / time.Second); got != tc.want {
                t.Fatalf("got %d, want %d", got, tc.want)
            }
        })
    }
}

测试名称直接写出边界，后续有人把实现改成浮点四舍五入时，差异会立刻暴露。若协议允许小数，再增加 1.75 的浮点断言；若协议不允许，就把截断策略写进接口说明。

常见误区与排查顺序

• 看到 int(d) 就以为是秒：先检查接收方的单位约定。
• 把 d.Milliseconds() 当成精确换算：它返回整数毫秒，微秒以下部分同样会被截掉。
• 用 float64 解决所有问题：展示适合浮点，计时控制和超时比较仍应优先使用 Duration。
• 忽略负数：过期时间、时间差和时钟修正可能出现负值，向上取整逻辑不能直接套用。

相关问答

time.Duration 能直接和整数比较吗？

可以，但整数会被转换到 Duration 的纳秒语义，代码可读性通常不如写成 3*time.Second。

Milliseconds 方法会四舍五入吗？

不会。它返回整数毫秒，低于一毫秒的部分会被截断。

什么时候应该使用 Round？

只有业务明确需要最近单位时才使用 d.Round(time.Second)；超时和截止时间不要为了显示效果改变原值。

把单位转换留在边界处

时间值在程序内部尽量保持 time.Duration，与定时器和上下文 API 直接对接；进入 JSON、数据库或外部协议时，再根据字段契约转换成秒或毫秒。这样既保留了控制逻辑的精度，也让一次“转整数”不会悄悄改变业务含义。