Go JSON 数字为什么反序列化后精度丢失

我第一次遇到这个问题，是接口里的订单号明明是 9007199254740993，放进 map[string]any 后再打印，却变成了 9007199254740992。看起来像是 JSON 被截断，实际是默认解码路径把 JSON 数字放进了 float64，大整数在浮点表示里已经没有足够的精确位数。

处理思路很简单：结构固定就直接用 int64 等明确类型；结构不固定但必须保留数字字面量，就给 Decoder 调用 UseNumber，把判断推迟到业务层。不要先让数字变成 float64，再试图把它“转回精确整数”。

为什么 map[string]any 会让大整数变成不精确的 float64

官方 encoding/json 的规则是：当目标是接口值时，JSON number 默认解码为 float64。这不是 Go 把 JSON 读错了，而是目标类型没有告诉解码器“它必须是整数”。

官方地址：https://pkg.go.dev/encoding/json

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    input := []byte(`{"order_id":9007199254740993}`)
    var payload map[string]any

    // 目标是 any 时，默认规则会把 JSON number 放进 float64。
    if err := json.Unmarshal(input, &payload); err != nil {
        panic(err)
    }

    // 这里的类型断言只是在观察结果，不能挽回已经丢失的位。
    fmt.Printf("类型=%T，值=%.0f\n", payload["order_id"], payload["order_id"])
}

上面的输出可以理解为“类型是 float64，值已经落在相邻可表示的整数上”。关键边界不是 JSON 文本长度，而是浮点数能否精确承载这个整数。只要接口层的字段是业务 ID，就不应该用 any 作为最终类型。

固定结构时，让目标类型直接表达精度要求

如果接口结构稳定，最省心的做法是定义结构体。订单号、数据库主键、毫秒时间戳等不能被四舍五入的字段，用 int64 接收；如果上游把 ID 当作字符串传输，则用 string 与协议保持一致。

type Order struct {
    OrderID int64 `json:"order_id"`
    Amount  int64 `json:"amount"`
}

func decodeOrder(data []byte) (Order, error) {
    var order Order

    // 结构体字段提供了目标整数类型，避免经过 float64。
    if err := json.Unmarshal(data, &order); err != nil {
        return Order{}, fmt.Errorf("解析订单: %w", err)
    }
    return order, nil
}

这里还有一个容易混淆的点：int64 解决的是整数精度和范围，不能替你解决小数金额的十进制舍入问题；字段含义不同，类型也要不同。

UseNumber 怎样把解析决策推迟到业务层

结构不固定时，可以使用流式解码器并调用 UseNumber。它会让接口值里的数字变成 json.Number，这个类型本质上保留了 JSON 数字字面量，之后再按字段语义选择 Int64 或 Float64。

func decodeDynamic(data []byte) (map[string]any, error) {
    decoder := json.NewDecoder(bytes.NewReader(data))

    // 先保留数字文本，避免动态对象默认落到 float64。
    decoder.UseNumber()

    var payload map[string]any
    if err := decoder.Decode(&payload); err != nil {
        return nil, fmt.Errorf("解析动态 JSON: %w", err)
    }
    return payload, nil
}

func readOrderID(payload map[string]any) (int64, error) {
    number, ok := payload["order_id"].(json.Number)
    if !ok {
        return 0, fmt.Errorf("order_id 不是 JSON number")
    }

    // 业务已经确认这是整数，所以在这里选择 Int64。
    return number.Int64()
}

UseNumber 不是“自动保证所有数字安全”，它只是把决定权留在还没有发生浮点转换的位置。调用 Float64 仍然会回到浮点语义；调用 Int64 则会在字面量不适合整数时返回错误。

上线前用四个问题定位精度丢失

1. 目标变量是不是 map[string]any、[]any 或普通 interface{}？如果是，先检查默认的 float64 路径。
2. 字段是“必须相等的整数”还是“允许近似的数值”？前者不要在中途转浮点。
3. 上游是否把 ID 用 JSON 字符串传输？如果协议如此，Go 端不要为了方便改成数字。
4. 动态对象是否在解析后才决定字段语义？如果是，入口使用 UseNumber，并在业务边界处理解析错误。

我现在排这类问题，第一步不再盯着日志里的最终数字，而是先打印它在容器中的动态类型。类型已经是 float64 时，继续做类型转换通常只是把错误藏得更深；把精度决策提前到 JSON 解码目标，修复才稳定。

相关问题

为什么 int64 字段解析超大数字会报错？

因为目标类型有范围限制。encoding/json 会报告类型或溢出错误，调用方应保留错误，不要把零值当成合法 ID。

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

不能把它当作普通数值直接运算。先根据业务语义调用 Int64 或 Float64，并处理返回的错误。

把所有 JSON 数字都改成字符串就一定好吗？

不一定。字符串能保护文本，但会改变协议语义；只有跨语言 ID 或协议明确要求文本时才这样做，普通数值仍应使用合适的数字类型。