Go JSON 解码后数字为什么变成 float64：UseNumber 与精确金额处理

把第三方 JSON 解码进 map[string]any 后，金额字段突然变成 float64，这是 Go 标准库的默认行为，不是数据源偷偷改了类型。只要解码目标是接口值，encoding/json 就会把 JSON 数字先放进浮点数；需要保留原始数字文本时，应改用 Decoder.UseNumber()，真正落库或计算金额时则优先使用整数最小单位或十进制定点方案。

查询结果可以临时用 float64，订单金额、账户余额和计费数量不要直接依赖它做精确比较。先决定数据的精度，再决定解码目标。

先复现：同一个 JSON 为什么得到两种数字类型

我们先准备一段简单的订单测试数据：

{"order_id":"A1042","amount":19.90,"quantity":2}

如果解码目标是提前定义好的结构体，字段类型完全由代码声明决定：

type Order struct {
    OrderID  string  `json:"order_id"`
    Amount   float64 `json:"amount"`
    Quantity int     `json:"quantity"`
}

var order Order
if err := json.Unmarshal(data, &order); err != nil {
    return err
}

但解码到 map[string]any 后再打印动态类型，结果通常是 float64：

var raw map[string]any
if err := json.Unmarshal(data, &raw); err != nil {
    return err
}
fmt.Printf("%T\n", raw["amount"]) // float64

JSON 本身只有一个“number”概念，没有 Go 的 int、int64 和 float64 标记。标准库在缺少目标字段类型时选择 float64，因此数字大、精度高或需要原样展示时，不能把这个默认值当作业务类型。

动态字段需要原样数字时，给 Decoder 加上 UseNumber

json.Decoder 可以把数字保存为 json.Number。它本质上保留了数字文本，之后由业务代码选择转成整数、浮点数或十进制库类型。

decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()

var raw map[string]any
if err := decoder.Decode(&raw); err != nil {
    return err
}

amount, ok := raw["amount"].(json.Number)
if !ok {
    return fmt.Errorf("amount is not a JSON number")
}
fmt.Println(amount.String()) // 19.90

这里的核对点不能停留在“断言成功”就结束，要接着校验数值本身是否符合业务侧的订单规则：

cents, err := strconv.ParseInt(strings.ReplaceAll(amount.String(), ".", ""), 10, 64)
if err != nil || cents 

上面的示例只适合固定两位小数且没有指数写法的输入。真实接口应使用专门的金额解析函数，明确处理 19、19.9、19.90、1e2 和超出 int64 的情况，不能用替换小数点的短写法直接上线。

金额字段的实现选择：结构体、整数还是十进制

如果接口协议是双方提前约定好的，最稳妥的方案是把金额字段定义成协议允许的适配类型。支付和计费相关系统里更常见的做法是金额字段传字符串，服务端收到后直接解析成以“分”为单位的整数：

type Payment struct {
    Amount string `json:"amount"`
}

// 例："19.90" -> 1990 分；解析失败、负数、超过范围都返回错误。

整数最小单位的优点是比较和加减都清楚，缺点是要在接口文档里写明币种和小数位。跨币种或需要税率、折扣等小数运算时，可以在边界层把 json.Number 转成可靠的十进制定点类型；不要因为“看起来只有两位小数”就让二进制浮点数贯穿整个账务流程。

如果字段只是统计展示，float64 也可以，但应在输出层格式化，不要这样判断金额相等：

if total == 19.90 { // 可能受二进制浮点表示影响
    // 不建议作为账务判定
}

把类型检查放在输入边界，而不是业务深处

动态 JSON 常见于配置、埋点和兼容多个版本的 webhook。建议解码后马上完成三件事：确认字段存在，确认它是允许的 JSON 类型，再把它转换成内部模型。这样后面的库存、订单和报表代码就不必到处写 .(float64)。

func readQuantity(v any) (int64, error) {
    n, ok := v.(json.Number)
    if !ok {
        return 0, errors.New("quantity must be a number")
    }
    value, err := strconv.ParseInt(n.String(), 10, 64)
    if err != nil || value 

如果上游可能发送 2.0，就不要悄悄截断成 2。先在协议层决定是否接受小数，再实现严格解析；否则同一个字段在不同调用方之间会出现难以追踪的语义差异。

常见失败现象与可复现检查

常见问题：JSON 数字类型怎么选

为什么类型断言成 int 会直接失败？

因为接口解码默认保存的是 float64，不是 int。短期兼容可以判断 float64 后做范围检查，但新代码更适合用结构体或 UseNumber，避免在业务层散落类型转换。

UseNumber 会自动保证金额精度吗？

不会。它只是把数字文本保留下来，精确与否取决于后续解析和计算。把 json.Number 再转回 float64，仍然会回到浮点精度边界。

为什么大整数解码后末尾数字变了？

大整数落入 float64 后可能无法保持每一位精确表示。订单号、流水号和雪花 ID 应在 JSON 中使用字符串，或在动态解码时使用 UseNumber 后按 int64 范围解析。

最后的选择清单

• 字段稳定、类型明确：直接定义对应结构体，让编译器帮你做类型校验。
• 字段动态、数字需保留原样：使用 Decoder.UseNumber()。
• 金额与计费场景：优先用业务侧最小单位的整数存值，或者选成熟可靠的十进制定点实现。
• 数值进入业务逻辑前：完成字段存在性、类型合法性、数值范围和小数位数校验。
• 做回归测试时：至少覆盖整数、普通小数、指数形式、负数、超范围值和字段缺失这些场景。

看到 float64 时不用马上把它当成 bug。先看解码目标，再看字段的业务精度；这两个判断做对了，JSON 类型转换问题通常能在输入边界一次解决。