Go json.Decoder UseNumber 如何避免大整数变成 float64

把 JSON 解码到 map[string]any 后，订单号、时间戳或计数器突然变成 float64，这是 encoding/json 的默认行为：当目标是 interface{} 时，JSON 数字没有已知 Go 字段类型，只能先落到浮点数。只要数字可能超过浮点精度，后续再转整数就已经晚了。

需要解析动态 JSON 又不想让数字先经过 float64 时，在第一次 Decode 前调用 dec.UseNumber()。这样数字会进入 json.Number，之后再根据业务决定调用 Int64()、Float64() 或 String()。

调用decoder.UseNumber()之后，所有JSON数值不会被自动转成float64，而是以json.Number类型的字符串形式存放，你可以按需转成对应的整型或大数类型，全程不会出现精度损失。

为什么 map[string]any 会先把数字变成 float64

问题通常出在“字段结构不固定”的接口。下面的代码没有给 id 指定 Go 类型，解码器只能使用动态值的默认映射。注意示例中的注释解释了判断点，真正的错误不是 JSON 文本变了，而是数字太早被交给了浮点类型。

package main

import (
    "encoding/json"
    "fmt"
    "strings"
)

func main() {
    var payload map[string]any
    // 动态对象没有结构体字段类型，默认数字会落到 float64。
    err := json.NewDecoder(strings.NewReader(`{"id":9007199254740993}`)).Decode(&payload)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%T %v\n", payload["id"], payload["id"])
}

输出类型会是 float64。这类值再断言成整数时，可能得到一个已经丢失低位的结果。已知结构的接口应优先使用结构体字段；本文的 UseNumber 主要解决动态对象、扩展字段和透传场景。

UseNumber 保留数字文本，再决定如何转换

UseNumber 必须在对应的 Decode 之前调用。它不会修改 JSON，也不会把所有数字强行变成整数，而是让动态值中的数字使用 json.Number 承载。json.Number 本质上保留了数字字面量，因此转换时机回到了业务代码。

package main

import (
    "encoding/json"
    "fmt"
    "strings"
)

func main() {
    var payload map[string]any
    dec := json.NewDecoder(strings.NewReader(`{"id":9007199254740993,"ratio":1.25}`))
    // 在首次 Decode 前保留数字字面量，避免先经过 float64。
    dec.UseNumber()
    if err := dec.Decode(&payload); err != nil {
        panic(err)
    }

    idText := payload["id"].(json.Number).String()
    id, err := payload["id"].(json.Number).Int64()
    if err != nil {
        // 超出 int64、带小数或格式不符时必须显式处理。
        panic(fmt.Errorf("id 不是可接受的 int64: %w", err))
    }
    fmt.Println(idText, id)
}

这里有两个不同动作：String() 适合把原始数字写入日志、签名材料或下游 JSON；Int64() 适合业务确实定义为有符号整数的字段，并且必须检查返回的错误。浮点比例则可以显式调用 Float64()，不要因为字段名看起来像数字就统一走整数转换。

UseNumber 解决不了哪些问题

第一，目标如果是明确的结构体，直接把字段声明为 int64、uint64 或自定义类型通常更清楚；UseNumber 不会替代领域建模。第二，它只影响解码到动态值时的数字承载方式，不能把 JSON 字符串 "9007199254740993" 自动变成数字，字符串仍需由业务决定是否解析。第三，Int64() 只接受可表示为有符号 64 位整数的字面量，失败必须留在当前边界处理。

如果使用同一个 Decoder 连续读取多个 JSON 值，保持“配置 Decoder、再开始 Decode”的顺序；不要在已经读取部分数据后才临时补上 UseNumber。对来自外部系统的字段，还应把类型断言写成带判断的形式，避免把错误输入变成 panic。

常见问题

UseNumber 会让所有数字都变成字符串吗？

不会。只有解码到 interface{}、map[string]any 或类似动态容器中的数字会变成 json.Number；它不是 JSON 字符串，仍可调用 Int64() 或 Float64()。

只调用 Int64 不调用 UseNumber 可以吗？

如果值已经默认解码为 float64，就没有 json.Number 可以调用了。要保留原始数字，必须在首次 Decode 前启用 UseNumber，或者改用字段类型明确的结构体。

大整数只要没有超过 int64 就一定安全吗？

不一定。安全前提是它没有先经过浮点转换，并且输入字面量符合整数格式。UseNumber 负责保留入口，Int64 的错误检查负责守住转换边界。

排查这类问题时，先问“这个数字什么时候失去原始文本”，再决定是结构体建模、UseNumber + Int64，还是全程保留 String()。这样比在结果已经变成 float64 后再猜测原值可靠得多。