Go json/v2 FormatDurationAsNano 怎样编码 time.Duration

在 encoding/json/v2 里，time.Duration 默认没有 JSON 表示，直接编码会返回 SemanticError。如果接口约定使用“纳秒数”，应显式传入 json.FormatDurationAsNano(true)；这样编码结果是没有小数和指数的 JSON number，数值代表纳秒。编码和解码两端要使用同一选项，别把它误解成带单位的字符串格式化。

官方文档：https://pkg.go.dev/encoding/json/v2

先把错误现象分层：默认表示为什么失败

我在迁移 v1 JSON 代码时，最容易误判的是“字段类型是整数，所以应该能直接写出”。time.Duration 的底层确实与整数有关，但 v2 先看类型的 JSON 语义：它默认没有可用表示，因此不是正常输出一个数字，而是报告语义错误。

package main

import (
    "fmt"
    "time"

    json "encoding/json/v2"
)

type Config struct {
    Timeout time.Duration
}

func main() {
    cfg := Config{Timeout: 1500 * time.Millisecond}
    _, err := json.Marshal(cfg)
    if err != nil {
        // v2 默认没有给 time.Duration 选定 JSON 表示，先保留原错误。
        fmt.Printf("编码失败: %T %v\n", err, err)
        return
    }
    // 这里不把未报错当成时间单位已经正确，需要继续核对协议约定。
    fmt.Println("编码成功")
}

这段代码只展示排查入口，不是本机运行报告。排查时先确认错误来自 time.Duration 的默认表示，而不是把所有 SemanticError 都归因于时间字段。若结构里还有自定义 Marshaler、无效字段或不支持的类型，应分别定位。

把 FormatDurationAsNano 放在真正的编码入口

修复动作很小，但位置要对：在调用 Marshal、MarshalWrite 或对应编码入口时传入 json.FormatDurationAsNano(true)。它是一个 Options，不是要写进结构体标签的字符串。

package main

import (
    "fmt"
    "time"

    json "encoding/json/v2"
)

type Config struct {
    Timeout time.Duration
}

func main() {
    cfg := Config{Timeout: 1500 * time.Millisecond}
    data, err := json.Marshal(&cfg,
        // 显式选择“纳秒数”表示，避免依赖 v2 的默认行为。
        json.FormatDurationAsNano(true),
    )
    if err != nil {
        // 编码入口统一返回错误，调用方可以把协议错误与 IO 错误分开。
        fmt.Println("编码失败:", err)
        return
    }
    // 按协议检查这是 JSON number，而不是带单位的字符串。
    fmt.Println(string(data))
}

对这个示例，协议层的期望表示是 1500000000，也就是 1.5 秒对应的纳秒数；这是根据单位换算写出的预期示例，不是本机执行输出。若改用 MarshalWrite 写入响应体，选项仍放在它的可变参数中，规则不变。

不要把 FormatDurationAsNano(true) 与 StringifyNumbers(true) 混为一谈。前者决定 time.Duration 是否按纳秒数编码；后者会把原本的 JSON number 放进 JSON string，属于另一层协议选择。是否需要字符串，要由接收方的数字精度和协议约定决定。

嵌套字段和解码端，检查选项是否贯穿

这个选项不是只对顶层的一个 duration 字段生效。v2 编解码会递归处理结构、切片和指针中的字段，因此配置对象里有 []Job、嵌套结构时，也要把协议选项放到同一个编码或解码入口。图片中的连线是静态依赖关系，不表示某次执行顺序。

package main

import (
    "fmt"
    "time"

    json "encoding/json/v2"
)

type Job struct {
    RetryAfter time.Duration
}

type Config struct {
    Timeout time.Duration
    Jobs    []Job
}

func main() {
    input := []byte(`{"Timeout":5000000000,"Jobs":[{"RetryAfter":250000000}]}`)
    var cfg Config
    if err := json.Unmarshal(&input, &cfg,
        // 解码端沿用同一纳秒协议，避免编码和解码单位不一致。
        json.FormatDurationAsNano(true),
    ); err != nil {
        // 真实服务应区分 JSON 语义错误与请求读取错误。
        fmt.Println("解码失败:", err)
        return
    }
    // 这里的字段值按 time.Duration 接收纳秒数，不是字符串解析结果。
    fmt.Println(cfg.Timeout, cfg.Jobs[0].RetryAfter)
}

注意 time.Duration 的纳秒数是整数协议。JSON 文本里写 "5s" 并不会因为使用了这个选项就自动变成时间间隔字符串解析；如果协议选择字符串，需要另行设计自定义类型或 Marshaler，不要悄悄改写字段含义。

遇到仍然失败时，按证据排查而不是换单位

官方文档说明，v1 的 time.Duration 默认就是十进制纳秒数，而 v2 默认没有表示；FormatDurationAsNano 正是控制这一差异的选项。迁移时可以显式加入它来保持旧协议，但最好把协议单位写进接口文档和测试数据，避免未来改成字符串时无人察觉。

常见问题

FormatDurationAsNano 会输出“1.5s”吗？

不会。它选择的是不带小数和指数的 JSON number，数值表示纳秒；“1.5s”属于字符串协议，需要单独定义。

只在 Marshal 时传选项，Unmarshal 可以省略吗？

不建议。解码端同样需要知道纳秒数是 time.Duration 的表示，通常应在对应的 Unmarshal 或 UnmarshalRead 入口传入同一选项。

可以用字段标签替代这个选项吗？

本文讨论的 v2 标准选项不是普通 JSON 标签。若要字符串时间或其他自定义表示，应实现明确的类型级编码逻辑，并把协议和错误边界写清楚。

最后可以用一张清单收尾：确认使用的是 encoding/json/v2，确认字段类型是 time.Duration，确认编码和解码入口都传入 json.FormatDurationAsNano(true)，确认协议单位是纳秒，并确认没有被 StringifyNumbers 或自定义 Marshaler 改成字符串。