Go json.Decoder.UseNumber 怎样避免 JSON 数字精度丢失

当 JSON 被解码到 map[string]any 或其他 interface{} 容器时，Go 默认把数字放成 float64。对于较大的整数，这一步可能已经改变了原始数值。解决办法是先创建 json.Decoder，调用 UseNumber()，让数字以 json.Number 保留，再按业务需要转成整数、浮点数或原始文本。

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

默认解码为什么会让大整数变得不可靠

官方 encoding/json 文档规定，JSON 解码到 interface{} 时，数字默认使用 float64。这对金额之外的普通比例、计数通常够用，但 IEEE 754 双精度并不能精确表示所有很大的整数。问题发生在“进入动态容器”的那一刻，而不是后面把 float64 断言成其他类型时才发生。

下面的示例故意使用动态对象。调用 UseNumber 后，数字不会立即被解释成浮点数，而是以 json.Number 进入 map：

package main

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

func main() {
    input := `{"id":9007199254740993,"ratio":0.125}`
    dec := json.NewDecoder(strings.NewReader(input))
    dec.UseNumber() // 让动态字段先保留为 json.Number。

    var value map[string]any
    if err := dec.Decode(&value); err != nil {
        panic(err) // 输入无效时不要继续使用不完整的 map。
    }

    id, ok := value["id"].(json.Number)
    if !ok {
        panic("id 不是 json.Number") // 类型不符通常说明解码目标或入口发生了变化。
    }
    fmt.Println(id.String()) // 仍可得到原始数字文本。
}

这里的关键不是让所有数字都变成某个更大的数值类型，而是把“如何解释数字”的决定延后。图1把 JSON 数字、解码器、动态容器、float64 与 json.Number 的静态职责放在一起；它是结构说明图，不是运行截图。

UseNumber 应该放在 Decode 之前

UseNumber 是 Decoder 的设置方法，要在相关 Decode 调用之前执行。它只改变数字进入动态接口值时的表示方式，不会自动改变已经填充的值，也不会把结构体字段从 int64 改成 json.Number。

如果目标是结构体，字段类型本身就是更清晰的契约：

type Event struct {
    ID    int64   `json:"id"`
    Ratio float64 `json:"ratio"`
}

func decodeEvent(data []byte) (Event, error) {
    var event Event
    // 强类型字段直接按字段类型解析，UseNumber 不参与这个选择。
    if err := json.Unmarshal(data, &event); err != nil {
        return Event{}, err // 类型不匹配或超出目标类型范围时交给调用方处理。
    }
    return event, nil
}

因此，UseNumber 更适合字段集合不固定、同一字段需要根据上下文决定精度，或需要保留原始数字文本的入口。对于固定协议，优先使用结构体字段；对于动态字段，再使用 Decoder 加上 UseNumber。

json.Number 的三种消费方式要分清

json.Number 是一个表示 JSON 数字字面量的字符串类型。拿到它以后，选择哪个方法就是业务边界：要保留精确文本就调用 String；确定是整数且范围可接受就调用 Int64；能够接受浮点近似时才调用 Float64。

func readID(value any) (int64, error) {
    number, ok := value.(json.Number)
    if !ok {
        return 0, fmt.Errorf("期望 json.Number，实际是 %T", value)
    }

    // Int64 同时检查整数格式和 int64 范围，不能忽略返回的 error。
    id, err := number.Int64()
    if err != nil {
        return 0, fmt.Errorf("id 不是可接受的 int64: %w", err)
    }
    return id, nil
}

func keepLiteral(value any) (string, error) {
    number, ok := value.(json.Number)
    if !ok {
        return "", fmt.Errorf("期望 json.Number，实际是 %T", value)
    }
    // String 不做数值换算，适合审计字段或需要原样转发的数字。
    return number.String(), nil
}

不要把 UseNumber 理解成“自动获得任意精度”。如果整数超过 int64 范围，Int64 仍会报错；如果调用 Float64，结果仍遵循浮点数的精度边界。图2对应这三个消费出口和错误处理边界，属于静态说明图。

把数字精度决策放进接口设计

实际项目中可以用下面的检查清单决定是否启用 UseNumber：

• 目标是 map[string]any、[]any 或嵌套动态值，并且数字可能超过浮点精确整数范围吗？是，就在第一次 Decode 前调用它。
• 字段是固定协议并且目标类型明确吗？优先定义结构体，直接用 int64、uint64 或 float64 表达契约。
• 这个数字需要原样转发、签名或审计吗？保留 json.Number.String()，不要先转 float64。
• 需要整数运算吗？调用 Int64() 后检查错误；需要浮点计算吗？明确接受近似，并检查 Float64() 的错误。

常见问题

UseNumber 能不能修复已经解码成 float64 的数据？

不能。它只对之后由该 Decoder 解码的动态数字生效；已经发生的浮点转换无法从原值推回。

调用 UseNumber 后所有字段都会变成 json.Number 吗？

不会。它主要影响动态接口值中的 JSON 数字；字符串、布尔值、数组和对象仍按各自规则解码，结构体字段也按声明类型处理。

json.Number.String() 返回的是带引号的 JSON 字符串吗？

不是。它返回数字字面量本身，例如 9007199254740993，不包含 JSON 字符串引号。