Go time.Duration.String 处理负值和纳秒精度：日志展示边界

线上日志里出现过一行 latency=-1.5ms，值本身没有错，真正容易误判的是读日志的人：负号、单位和纳秒尾数一旦被手工截断，排查方向就会跑偏。Go 的 time.Duration.String 会根据数值自动挑选可读单位，负值也会保留；需要固定精度时，再显式配合 Truncate。

String 负责“把完整 duration 变成人能读的文本”，不会替你四舍五入；如果展示层必须固定到毫秒，应先明确调用 Truncate(time.Millisecond)，并接受精度被舍弃。

先看清 time.Duration 的真实数值

time.Duration 是带单位的整数类型，底层刻度是纳秒。也就是说，1500*time.Microsecond 并不是一个模糊的“约 1 毫秒”，而是精确的 1,500,000 纳秒。负 duration 也遵循同一规则，只是整数符号变成负数。

package main

import (
    "fmt"
    "time"
)

func main() {
    samples := []time.Duration{
        1500 * time.Microsecond,
        -1500 * time.Microsecond,
        1234567 * time.Nanosecond,
    }
    for _, d := range samples {
        fmt.Printf("raw=%d text=%s\n", d, d.String())
    }
}

这段程序的关键关系是：输入先进入 time.Duration，再由 String 选择组合单位，最后得到日志文本。这里的 raw 是纳秒整数，text 才是格式化结果。

String 为什么显示成 -1.5ms

String 的职责是尽量短而不丢掉可表达的信息。对 -1500*time.Microsecond，它会输出 -1.5ms；对 1234567*time.Nanosecond，则会保留纳秒部分。负号不会被移到单位后面，也不会因为单位自动选择而消失。

因此日志审阅时不要看到 ms 就默认它是整数毫秒。要做数值比较，直接比较 duration；要给人看，再比较 String 文本。把字符串重新切成数字，反而容易引入单位误读。

需要固定毫秒时，先明确 Truncate 的取舍

package main

import (
    "fmt"
    "time"
)

func main() {
    d := -1500 * time.Microsecond
    fmt.Println("原始:", d.String())
    fmt.Println("截断到毫秒:", d.Truncate(time.Millisecond).String())
}

Truncate 会把 duration 截到给定单位的整数倍。对负值它同样向零靠近，所以 -1.5ms 截断到毫秒后是 -1ms，不是 -2ms。这正是展示精度与统计精度的分界：日志可以选择简短，但告警阈值判断最好保留原始 duration。

日志和指标各自应该保存什么

如果字段用于人工排查，推荐同时保留原始 duration 的 String 文本和一个明确命名的截断字段，例如 latency_ms_display。如果字段要进入指标聚合，使用数值或统一单位的整数，不要把 1.5ms 和 1500µs 当成两种业务状态。

还要注意零值：time.Duration(0).String() 是 0s。它并不表示“没有采样”，只是测量结果确实为零；没有采样应使用单独的状态或指针表达。

常见问题

String 会四舍五入吗？

不会把 duration 先四舍五入到某个固定单位。它会选择可读表示并保留必要精度；固定展示精度应显式调用 Truncate，并在字段名或说明里写明损失的精度。

负 duration 是不是异常值？

不一定。两个时间点相减时顺序相反就会得到负值。它是否异常取决于业务语义，不能仅因日志带负号就把数据改成绝对值。

为什么不直接把 String 结果切掉小数？

字符串切割不知道当前单位，也无法正确处理纳秒、微秒和负值。应该在 duration 层完成单位转换或截断，再把结果格式化给读者。

小结

time.Duration 保存精确纳秒值，String 负责可读输出，Truncate 负责明确舍弃精度。先保留原始 duration，再按日志、指标和阈值判断分别决定展示形式，能避免把负值或小数毫秒误当成程序错误。