Go json.Decoder避免 JSON 数字被转成浮点的解析方案

接口收到的 JSON 如果直接解码到 map[string]any，数字默认会落成 float64。订单号、流水号或高精度金额一旦先经过浮点表示，后面再转整数就可能得到与原文不同的值。处理动态 JSON 时，比较稳妥的做法是在 Decode 前调用 UseNumber()，让数字先保留为 json.Number，等知道业务语义后再转换。

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

数字为什么会先变成 float64

问题通常不在 JSON 文本，而在目标类型。encoding/json 把对象解码到 interface{} 时，布尔值、字符串、数组和对象都有默认映射，其中 JSON 数字对应 float64。代码即使没有报错，也已经选择了浮点表示：

package main

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

func main() {
    // 动态对象便于接收未知字段，但数字会按默认规则落到 float64。
    var payload map[string]any
    dec := json.NewDecoder(strings.NewReader(`{"id":9007199254740993}`))
    if err := dec.Decode(&payload); err != nil {
        // 输入格式错误时停止，避免继续使用不完整对象。
        panic(err)
    }
    fmt.Printf("%T %v\n", payload["id"], payload["id"])
}

如果目标是带有 int64 字段的结构体，解码器会按字段类型赋值；只有把数字交给接口或动态 map 时，才需要额外处理默认浮点边界。

在 Decode 前启用 UseNumber 保留字面量

UseNumber 是解码器配置，必须在读取目标之前设置。这样动态对象里的数字会以 json.Number 保存，数字文本可留到业务层判断。

func decodeDynamic(input string) (map[string]any, error) {
    // 先保留数字字面量，再由业务代码选择目标类型。
    dec := json.NewDecoder(strings.NewReader(input))
    dec.UseNumber()

    var payload map[string]any
    if err := dec.Decode(&payload); err != nil {
        // 语法错误和读取错误都向上返回。
        return nil, err
    }
    return payload, nil
}

这段配置不会把所有数字自动变成 int64，也不会验证字段含义。它只是把“先转浮点”改成“先保留数字字面量”，因此大整数、指数写法和小数都能在下一层明确处理。

按业务语义转换 json.Number

json.Number 表示 JSON 数字字面量。需要显示、记录或交给高精度解析器时用 String()；确定是有符号整数时用 Int64() 并检查错误；确实需要浮点计算时才用 Float64()。

func readIDAndRatio(payload map[string]any) (int64, float64, error) {
    // 先确认字段类型，避免把字符串或 nil 当数字使用。
    idNumber, ok := payload["id"].(json.Number)
    if !ok {
        return 0, 0, fmt.Errorf("id 不是 JSON 数字")
    }
    id, err := idNumber.Int64()
    if err != nil {
        // 超出 int64 或带小数时不静默截断。
        return 0, 0, fmt.Errorf("id 转 int64 失败: %w", err)
    }

    ratioNumber, ok := payload["ratio"].(json.Number)
    if !ok {
        return 0, 0, fmt.Errorf("ratio 不是 JSON 数字")
    }
    ratio, err := ratioNumber.Float64()
    if err != nil {
        // 只有比例允许浮点时才走 Float64。
        return 0, 0, fmt.Errorf("ratio 转 float64 失败: %w", err)
    }
    return id, ratio, nil
}

金额、计数器和外部标识不要因为转换方便就统一调用 Float64()。金额可以保留文本交给定点数方案，标识通常直接保留字符串；Int64() 也只适合明确落在有符号 64 位范围内的值。

三种解析方式的选择边界

字段固定时，结构体最清楚；字段动态但只需要保留数字精度时，用 UseNumber 加 map[string]any；某个字段需要延迟交给另一套规则解析时，再考虑 json.RawMessage。

实际接口可以混用：外层用结构体固定公共字段，少数扩展字段使用 json.RawMessage；完全动态的对象才适合 UseNumber。这比把整份请求体都变成动态 map 更容易维护。

用三组输入核对精度和错误

准备一个大整数、一个带小数的比例，以及一个不能落入 int64 的值。检查重点是大整数是否仍为 json.Number、Int64() 是否返回错误、只有比例字段才进入 Float64()。

• 大整数：先用 String() 对照原始数字，再决定是否能用 Int64()。
• 小数：不要强行调用 Int64()，确需计算时才转 Float64()。
• 非法目标：保留转换错误，不要用零值覆盖原始数字。

相关问题

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

它主要影响解码到接口值时的数字表示。结构体字段仍按声明类型解码，是否成功取决于 JSON 数字与目标类型是否匹配。

json.Number 能彻底避免精度问题吗？

它避免数字过早经过 float64，但最终转成 float64 仍有浮点精度边界。精确金额应保留文本或使用定点数方案。

为什么不用 Unmarshal 直接设置 UseNumber？

UseNumber 属于 Decoder 配置；若直接用 json.Unmarshal 解码到接口，调用点没有这个 Decoder 选项。

Int64 转换失败时怎么办？

把它当作输入不符合当前字段语义处理，记录字段名和原始字面量，再决定改用字符串、定点数或其他明确范围的数值类型。