json.Number 如何避免大整数精度丢失

Go 的 encoding/json 在把 JSON 解码到 interface{} 时，数字默认会变成 float64。当输入是订单号、雪花 ID 或超过浮点数安全整数范围的计数值时，直接这样解码可能让数字的末尾发生变化。

先看清默认解码为什么会改掉大整数

问题通常出现在动态 JSON：代码使用 map[string]any 或 any 接收数据，然后把某个数字断言成浮点数。float64 只有有限的有效整数精度，数字看起来仍然是一个合法浮点值，但它不一定还是输入中的那串整数。

下面的示例只用于展示默认行为。重点不是记住某个输出，而是看到数字一旦先进入 float64，后续再转回整数已经无法找回原始字面量。

package main

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

func main() {
    input := `{"id":9007199254740993}`
    var data map[string]any

    // 默认解码会把未指定目标类型的 JSON 数字放进 float64。
    if err := json.NewDecoder(strings.NewReader(input)).Decode(&data); err != nil {
        // 解析失败要立即返回，避免继续使用不完整的数据。
        panic(err)
    }

    // 这里拿到的是 float64；此时原始整数文本已经不在了。
    fmt.Printf("%T: %v\n", data["id"], data["id"])
}

用 UseNumber 把数字保留为 json.Number

动态字段需要保留数字原样时，应该使用 Decoder 而不是直接调用 json.Unmarshal，并在解码前调用 UseNumber()。这样，落到 any 中的数字会以 json.Number 保存；它本质上保留了 JSON 数字的文本表示，转换时再决定目标类型。

package main

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

func main() {
    input := `{"id":9007199254740993}`
    decoder := json.NewDecoder(strings.NewReader(input))

    // 先保留数字文本，再由业务代码选择整数或浮点数类型。
    decoder.UseNumber()

    var data map[string]any
    if err := decoder.Decode(&data); err != nil {
        // 解码错误不能被当作空对象继续处理。
        panic(err)
    }

    number, ok := data["id"].(json.Number)
    if !ok {
        panic("id 不是 json.Number")
    }

    // Int64 会检查格式与范围，错误必须向上返回。
    id, err := number.Int64()
    if err != nil {
        panic(err)
    }
    fmt.Println(id)
}

UseNumber 只改变动态字段里数字的落点，不会自动替你决定数字应该是金额、整数还是高精度小数。真正使用前仍要根据字段语义选择转换方法。

按目标类型完成转换与错误处理

json.Number 常见的三个出口分别是 String()、Int64() 和 Float64()。其中 String() 适合继续交给十进制库或作为原样文本；Int64() 适合范围明确的整数；Float64() 只适合确实允许浮点近似的字段。

func parseBigInteger(number json.Number) (*big.Int, error) {
    // 先取原始十进制文本，避免经过 float64 的舍入。
    text := number.String()
    value := new(big.Int)

    // SetString 返回 ok=false 时，输入不是目标进制的合法整数。
    if _, ok := value.SetString(text, 10); !ok {
        return nil, fmt.Errorf("无效的大整数 %q", text)
    }
    return value, nil
}

示例需要补齐 math/big、encoding/json 和 fmt 导入。这里把错误显式返回，是为了让调用方决定拒绝请求、记录异常还是降级为字符串；不要用零值掩盖溢出。

结构体字段与边界场景怎么选

JSON 结构稳定时，可以直接声明字段：

type Payload struct {
    // json.Number 让字段保留输入数字的文本形式。
    ID json.Number `json:"id"`
}

func decodePayload(input []byte) (Payload, error) {
    var payload Payload
    // Unmarshal 直接填充 json.Number，不需要先经过 interface{}。
    if err := json.Unmarshal(input, &payload); err != nil {
        return Payload{}, err
    }
    return payload, nil
}

如果输入是带小数点或指数的数字，Int64() 会报错，这不是精度丢失，而是目标类型与输入语义不匹配。若数据可能超过 int64，保留 String() 结果或转 big.Int；若字段是金额，则应采用明确的十进制表示，而不是为了“能解析”强行调用 Float64()。

常见问题

只把 float64 再转成 int64 可以补救吗？

不能可靠补救。转换前的浮点值可能已经发生舍入；应从解码入口使用 UseNumber 或结构体字段使用 json.Number。

UseNumber 会让所有数字自动变成 int64 吗？

不会。它只保留数字文本，具体的整数、浮点或高精度处理仍由调用方选择。

json.Number 适合直接存入数据库吗？

先根据数据库列类型和业务范围决定转换。无法证明范围安全时，保留文本通常比先转成浮点数更稳妥。

参考：https://pkg.go.dev/encoding/json；Go 标准库源码中的数字转换逻辑会在默认模式下解析为 float64，启用 UseNumber 后保留为 json.Number。