Go json.Decoder 怎么保留 JSON 大整数而不先转成 float64

当 JSON 里的数字只是展示值时，默认解码通常够用；但当它是订单号、账务金额的最小单位，或者来自外部系统的长整型标识时，先把它放进 float64 就可能来不及挽回精度。对于标题中的场景，比较稳的做法是：创建 json.Decoder 后先调用 UseNumber，再 Decode 到 any。这样接口值里的数字会保留成 json.Number，等业务边界明确后再选择 String、Int64 或 Float64。

官方文档：https://pkg.go.dev/encoding/json#Decoder.UseNumber

这不是把所有数字都改成字符串，而是把“何时、按什么类型解释数字”的决定往后推。只有真正需要算术或写入固定类型时，才显式解析并处理范围错误。

先给这个模式取个名字：延迟数值解释

我在接收第三方 JSON 时，最容易踩的坑不是 JSON 语法，而是接口结构还没确定，数字的业务含义却已经被默认类型替我决定了。Decode(&value) 解到 any 后，普通数字默认进入 float64；一旦发生这个转换，后面再把它断言成整数，已经不是“恢复原文”，而是从浮点值重新猜一个整数。

因此可以把 UseNumber 看成一种很小的解析架构模式：输入层保留数字词面，领域层决定数字用途，存储层再落实成明确类型。它的价值不在于 API 多了一个方法，而在于把不可逆的类型转换推迟到了真正有上下文的地方。

什么压力下值得使用 UseNumber

这个模式适合“结构暂时未知，但数字精度不能由默认值替你决定”的输入。例如网关先接收一份不同版本的事件，审计层需要保留原始金额，或者规则引擎要先判断字段名再决定它是计数、比例还是标识符。此时先保存 json.Number，可以让后续代码看到数字的原始十进制文本。

它不等于所有 JSON 数字都应该这样处理。固定结构且字段就是 int64 的请求，可以直接用结构体字段接收；完全是人类展示用的测量值，直接解析为 float64 反而更简单。判断标准只有一个：当前这一层是否已经拥有足够信息来承担数值解释。

典型实现：先保留，再在边界解析

关键顺序只有一个：UseNumber 必须发生在 Decode 之前。它只影响解码到接口值时的数字表示，不会把已经声明为 int64 的结构体字段改成 json.Number。

package main

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

func main() {
    payload := `{"order_id":9007199254740993,"ratio":0.125}`

    // 先保留数字文本，避免接口值默认落成 float64。
    dec := json.NewDecoder(strings.NewReader(payload))
    dec.UseNumber()

    var raw map[string]any
    if err := dec.Decode(&raw); err != nil {
        // 输入层先返回解码错误，不要拿半成品继续做业务判断。
        panic(err)
    }

    // 只有确认它是整数业务字段后，才在边界处解析并检查范围。
    orderID, ok := raw["order_id"].(json.Number)
    if !ok {
        panic("order_id 不是 JSON 数字")
    }
    id, err := orderID.Int64()
    if err != nil {
        // 超出 int64 或包含非整数形式时，显式拒绝而不是静默截断。
        panic(err)
    }
    fmt.Println(id)

这里的 order_id 最终选择了 Int64，因为它被当作有范围的整数。若它只是需要原样转发的外部标识，则可以保留 orderID.String()，不要为了方便比较而把它转成浮点数。

反例：先落成 float64，再尝试补救

不调用 UseNumber 时，解码到 map[string]any 的数字会默认使用 float64。IEEE 754 双精度只能无损表示连续的整数到 2^53 附近；更大的整数可能与相邻数共享同一个浮点表示。比如 9007199254740993 这样的值，经过浮点转换后就不能再保证恢复为原始文本。

var raw map[string]any

// 这里没有 UseNumber，接口值里的 JSON 数字按默认规则变成 float64。
if err := json.Unmarshal([]byte(`{"order_id":9007199254740993}`), &raw); err != nil {
    // 解析失败时立即返回，避免把错误数据交给后续流程。
    panic(err)
}

value, ok := raw["order_id"].(float64)
if !ok {
    panic("order_id 不是默认的 float64")
}
fmt.Printf("%.0f\n", value) // 显示出的整数不再等价于输入文本

这个反例的重点不是某个打印结果，而是信息损失的时机：从十进制文本到 float64 是一次可能不可逆的解释。之后再做 int64(value)，只能得到当前浮点值对应的整数，不能证明它就是 JSON 中原来的整数。

后果：保留精度，也要承担显式选择

json.Number 是字符串形态的数字表示，既能通过 String 保留词面，也能通过 Int64 或 Float64 主动转换。这个设计把风险从“默认悄悄转换”变成“调用者必须选择结果”，代价是每个业务分支都要写清范围和错误处理。

还要留意一个容易混淆的边界：UseNumber 不会自动把数字变成精确的任意精度整数，也不会替你决定金额单位。需要更大范围时，应该在保留词面后接入明确的高精度类型或业务校验；需要金额时，则应先确定分、厘等单位和舍入规则。

最后用一张判断清单收口

• 是否把 JSON 解码到了 any、map[string]any 或 []any？是的话，先确认默认数字类型是否可接受。
• 是否存在超过 2^53 的整数、长整型标识或需要原样转发的数字？有的话，在 Decode 前调用 UseNumber。
• 拿到 json.Number 后，当前字段是标识符、整数、浮点值还是仅需展示？按这个业务语义选择方法。
• Int64 和 Float64 的错误是否被处理？不要把解析错误当作零值继续写入。
• 结构固定时，是否可以直接声明目标类型？如果可以，优先让结构体字段承担输入契约。

一句话总结：UseNumber 解决的是“不要在未知结构层过早解释数字”，不是“所有数字都不许转成浮点”。把解释推迟到拥有业务上下文的边界，再用明确的类型和错误处理完成转换，才是保留大整数的完整做法。

常见延伸问题

UseNumber 会影响结构体里的 int64 字段吗？

不会。它主要改变解码到接口值时数字的表示；结构体字段仍按字段声明的目标类型解码，并在不匹配或越界时返回错误。

json.Number 能直接参与加法吗？

不能。它是字符串形态的数字类型，应先按业务选择 Int64、Float64 或其他高精度解析方式，并处理返回的错误。

只想保存订单号，应该用 Int64 还是 String？

如果订单号只是不可计算的外部标识，优先保留 String() 或在输入契约中使用字符串；只有确实需要整数比较、范围校验或数值运算时，才使用 Int64。