Go time.Duration 怎么序列化成可读配置并正确反序列化

我在把服务超时写进配置文件时遇到过一个很容易忽略的分叉：time.Duration 在 Go 里本质上是纳秒数，但配置文件里更适合出现 500ms、2s 或 1m30s。如果直接把它当整数写出，读配置的人看不出单位；如果把不存在的 Duration.MarshalText 当成标准库方法，代码又会从一开始就编译不过。

稳妥的做法是分两层：标准库用 Duration.String() 生成可读文本，用 time.ParseDuration 解析带单位的文本；配置结构体再按需要包一层类型，实现 MarshalText 和 UnmarshalText。官方文档入口可以直接复制：https://pkg.go.dev/time#Duration.String、https://pkg.go.dev/time#ParseDuration。

结论：不要把 Duration 的底层纳秒值直接当配置格式。用 String/ParseDuration 定义文本约定，只有在配置框架需要文本接口时，才为字段增加一个小型适配类型；解析失败要把字段名和原始输入一起带回错误。

先确认 Duration 的可读文本边界

time.Duration 适合参与计算、比较和定时器调用，而配置文本需要可读性。标准库已经把这条边界分得很清楚：String 把时长格式化为带单位的字符串，ParseDuration 接受带单位的字符串并返回 Duration 与错误。

支持的常用单位包括 ns、us 或 µs、ms、s、m 和 h，一个字符串可以由多个带单位的片段组成，例如 2h45m。这也是配置里应该保留单位的原因：1500 这个数字无法独立表达它是纳秒、毫秒还是秒。

package main

import (
    "fmt"
    "time"
)

func main() {
    // 运行时值仍然是 Duration，String 只负责生成带单位的文本。
    d := 1500 * time.Millisecond
    text := d.String()

    // 解析入口接受带单位的配置文本，并返回错误供调用方处理。
    parsed, err := time.ParseDuration(text)
    if err != nil {
        fmt.Println("解析时长失败:", err)
        return
    }
    fmt.Println(text, parsed == d)
}

这里的重点不是把数字转成字符串，而是固定一个可往返的文本协议：写出时保留单位，读回时只接受 ParseDuration 能理解的格式。不要用 float64 秒数再自行拼接单位，否则小数精度和单位选择会变成额外的协议问题。

为什么不能直接写 Duration.MarshalText

标题里常说的“MarshalText”容易让人误以为 time.Duration 自带这个方法。实际上，Duration 的标准文本能力是 String 与 ParseDuration；encoding.TextMarshaler 和 encoding.TextUnmarshaler 是一组由具体类型实现的接口，不会凭空给所有类型增加方法。

因此下面这种写法不是标准库 API，不能作为直接调用：

// 错误示例：Duration 没有这个标准库方法。
text, err := time.Second.MarshalText()

如果配置库只需要字符串，直接在边界处使用 duration.String() 和 time.ParseDuration(value) 就够了。如果配置库会自动识别文本编解码接口，再定义一个包装类型，把接口实现集中在包装层。

用 DurationText 把配置字段接上文本接口

下面的包装类型只增加配置语义，不改变 time.Duration 的计算方式。写出时委托 String，读入时委托 ParseDuration，并把字段名放入错误信息，便于定位到底是哪一项配置有问题。

package config

import (
    "fmt"
    "time"
)

// DurationText 只负责配置边界，底层仍可转换回 time.Duration 参与计算。
type DurationText time.Duration

// MarshalText 把运行时值写成带单位的可读文本。
func (d DurationText) MarshalText() ([]byte, error) {
    return []byte(time.Duration(d).String()), nil
}

// UnmarshalText 解析配置文本，并保留字段上下文方便排错。
func (d *DurationText) UnmarshalText(data []byte) error {
    parsed, err := time.ParseDuration(string(data))
    if err != nil {
        return fmt.Errorf("timeout must be a duration: %q: %w", string(data), err)
    }
    *d = DurationText(parsed)
    return nil
}

// Config 的 Timeout 在配置层是文本，在业务层可转回 Duration。
type Config struct {
    Timeout DurationText
}

func (c Config) TimeoutDuration() time.Duration {
    // 显式转换，避免把配置包装类型和 Duration 混用。
    return time.Duration(c.Timeout)
}

这个类型满足文本编解码接口的形状，但是否会被某个配置库自动调用，仍取决于该库的约定。不能因为方法名正确，就假设所有 JSON、YAML 或自研配置读取器都会自动识别；接入前要看目标库的字段编解码规则。

字符串配置和 JSON 配置要分开设计

对 key=value、环境变量或命令行这类纯文本入口，UnmarshalText 通常就是清晰的适配点。对 JSON，如果希望配置文件中保存 "timeout":"2s"，建议显式实现 JSON 方法，避免把数值纳秒和字符串协议混在一起。

package config

import (
    "encoding/json"
    "fmt"
)

// MarshalJSON 明确约定 JSON 中的 timeout 是字符串，而不是纳秒整数。
func (d DurationText) MarshalJSON() ([]byte, error) {
    text, err := d.MarshalText()
    if err != nil {
        return nil, err
    }
    return json.Marshal(string(text))
}

// UnmarshalJSON 先要求 JSON 字符串，再复用统一的 Duration 文本解析。
func (d *DurationText) UnmarshalJSON(data []byte) error {
    var text string
    if err := json.Unmarshal(data, &text); err != nil {
        return fmt.Errorf("timeout must be a JSON string: %w", err)
    }
    return d.UnmarshalText([]byte(text))
}

这样 JSON 的协议就明确了：写出是带单位的字符串，读入先检查 JSON 类型，再检查 Duration 格式。若业务确实需要纳秒整数，也可以另设一个数值字段，但不要让同一个字段一会儿输出整数、一会儿输出字符串。

非法配置、空值和单位选择怎么处理

ParseDuration 返回错误时，不要静默改成零值。零值可能表示“立即超时”“关闭等待”或“使用默认值”，它和“配置写错”不是一回事。读取流程可以在更外层决定是终止启动、使用默认值还是提示用户，但包装类型至少应该把原始输入保留下来。

最后的落地取舍

如果配置来源本身就是字符串，直接调用 time.ParseDuration 是最小方案；如果多个字段都需要统一的文本约定，可以复用 DurationText；如果目标编码器不会自动识别 TextMarshaler，就像 JSON 示例一样，为该编码器提供显式的编解码方法。

我最终会把“运行时类型”和“配置适配类型”分开：业务计算继续使用 time.Duration，配置结构体使用包装类型或在加载层完成转换。这样既保留 Go 标准库的单位解析规则，也避免把底层纳秒整数泄漏成难以维护的配置协议。

相关问题

time.Duration 的 String 会不会丢失单位？

不会。它会生成带单位的文本；读回时交给 time.ParseDuration，不要自行按整数猜测单位。

能不能把 Duration 直接存成 int64？

可以，但那是纳秒数协议，适合内部二进制或明确约定的数值字段，不适合作为给人维护的配置格式。

为什么解析失败不能直接设成零值？

因为零值是一个合法的运行时值，不能替代“输入非法”。保留错误并由上层决定默认策略，才能区分配置缺失和配置写错。