Go json.Decoder.UseNumber 为什么不能影响 Marshal

在 Go 里，Decoder.UseNumber() 经常和“避免 JSON 大整数被转成 float64”一起出现。于是一个常见误解是：既然解码器启用了 UseNumber，后面的 json.Marshal 也应该自动保留原始数字。实际情况要分两层看：UseNumber 只改变特定的解码结果，Marshal 只读取当前手里那个 Go 值。

UseNumber 不是 Marshal 的全局开关。它只在数字被解码到 interface{} 时，把具体类型从 float64 改成 json.Number；如果中途已经转成别的类型，Marshal 不会知道之前是否调用过 UseNumber。

官方资料：https://pkg.go.dev/encoding/json

这篇文章按一个完整排查流程拆开四个问题：UseNumber 改了哪一步、Marshal 看什么、为什么有时看起来“间接生效”，以及应该如何选择承载类型。

UseNumber 到底改变了哪一步

官方文档对 UseNumber 的描述很窄：当 Decoder 把 JSON 解码到一个接口值时，数字使用 json.Number，而不是默认的 float64。这里有两个关键限定词：解码器和interface{}。

var value map[string]any
decoder := json.NewDecoder(strings.NewReader(`{"id":9007199254740993}`))
// 让 interface{} 中的数字保留为 json.Number，而不是默认的 float64。
decoder.UseNumber()
if err := decoder.Decode(&value); err != nil {
    // 解码失败时立即返回，避免继续使用不完整的动态值。
    return err
}

// value["id"] 的具体类型是 json.Number。
number, ok := value["id"].(json.Number)
if !ok {
    return fmt.Errorf("id 的类型不是 json.Number")
}
fmt.Println(number.String())

如果目标是一个字段类型已经写死的结构体，Decoder 会遵循字段声明，不会因为 UseNumber 把 float64 字段临时变成 json.Number：

type Payload struct {
    ID float64 `json:"id"`
}

var payload Payload
decoder := json.NewDecoder(strings.NewReader(`{"id":9007199254740993}`))
// UseNumber 不会改写 Payload.ID 的静态字段类型。
decoder.UseNumber()
if err := decoder.Decode(&payload); err != nil {
    // 目标字段不匹配时停止处理。
    return err
}
// payload.ID 仍然是 float64，精度边界由字段类型决定。

Marshal 看的是当前值，不是 Decoder 的历史设置

json.Marshal(v) 接收的是一个当前已经存在的 Go 值。它会递归遍历这个值，并按具体类型选择编码路径；它没有一个参数可以读取“这个值最初是否由 UseNumber 解码”。因此，调用链里前面有没有 UseNumber，不会单独改变 Marshal 的规则。

func encode(value any) ([]byte, error) {
    // Marshal 只观察 value 当前保存的具体值和类型。
    data, err := json.Marshal(value)
    if err != nil {
        // 把编码错误交给调用方，避免返回不完整 JSON。
        return nil, fmt.Errorf("marshal value: %w", err)
    }
    return data, nil
}

// 这里是 string，不会因为之前某个 Decoder 用过 UseNumber 就变回 JSON 数字。
value := map[string]any{"id": "9007199254740993"}
data, err := encode(value)
if err != nil {
    return err
}
fmt.Println(string(data))

这也是“UseNumber 不能影响 Marshal”这句话的准确含义：它不是编码器配置。只要你在解码之后把 json.Number 转成了 float64、string 或其他业务类型，Marshal 就按转换后的类型工作。

为什么有时看起来又像是影响了 Marshal

如果目标是 map[string]any，并且解码后没有改动其中的数字，UseNumber 产生的 json.Number 会继续留在 map 里。随后 Marshal 看到的确实是 json.Number，所以输出可以保留它代表的数字字面量。这里发生的是数据类型被保留下来，不是 Marshal 读取了 Decoder 的设置。

func decodeAndReencode(input string) ([]byte, error) {
    var value map[string]any
    decoder := json.NewDecoder(strings.NewReader(input))
    // 只改变动态对象中的数字承载类型。
    decoder.UseNumber()
    if err := decoder.Decode(&value); err != nil {
        return nil, fmt.Errorf("decode JSON: %w", err)
    }

    // 未把 json.Number 转成 float64 或 string，类型仍在 map 中。
    output, err := json.Marshal(value)
    if err != nil {
        return nil, fmt.Errorf("re-encode JSON: %w", err)
    }
    return output, nil
}

反过来，下面三种改动会切断这种间接关系：

• 把 json.Number 调用 Float64() 后存回 map，得到的是浮点值。
• 把它转成普通 string，Marshal 会按 JSON 字符串编码，而不是数字。
• 把它放进一个声明为 float64 的结构体字段，字段类型优先于 Decoder 的历史选项。

因此排查时不要只搜索 UseNumber()。沿着值的生命周期继续看：解码目标是什么、有没有类型断言、有没有数值转换、最后传给 Marshal 的变量具体是什么。

按目标选择保留方式

把需求分成三类，通常就不会把 UseNumber 和 Marshal 混在一起：

如果只是想让大整数在动态对象里不经过浮点转换，UseNumber 足够；如果要做业务运算，应该尽早落到明确的整数或自定义类型，并处理转换错误；如果要原样转发一段 JSON，则应考虑 RawMessage，而不是寄希望于 Marshal 记住 Decoder 的配置。

排查这类问题的速查流程

1. 先看 Decode 的目标：目标是 interface{} 还是静态结构体字段？只有前者的默认数字类型会被 UseNumber 改变。
2. 再看当前具体类型：在交给 Marshal 前，确认值仍是 json.Number、已经变成 float64，还是被转成了 string。
3. 最后看保留目标：要动态数字、业务计算还是原始 JSON，分别选择 json.Number、明确数值字段或 RawMessage。

一句话收束：UseNumber 决定“动态解码时把数字装进什么类型”，Marshal 决定“当前这个类型怎样输出 JSON”。两者之间只有数据类型传递关系，没有全局配置继承关系。

UseNumber 能保证任意 JSON 数字都不丢精度吗？

它能避免动态解码默认落到 float64，但后续如果转成浮点数，仍会受到浮点类型的精度边界影响。

为什么 json.Number Marshal 后没有加引号？

因为它代表的是 JSON 数字字面量；如果你的意图是输出字符串，应显式使用 string，并接受 JSON 字符串的引号。

Marshal 会知道某个值曾经调用过 UseNumber 吗？

不会。Marshal 只接收当前值；它能表现出 UseNumber 的效果，是因为 json.Number 仍然被保存在数据结构中。