Go JSON 数字精度丢失的类型选择

Go 里最容易被忽略的 JSON 数字问题，是把数据解码到 interface{} 后才发现一个较大的整数已经变了。根因不是 JSON 文本突然不可靠，而是 encoding/json 在没有具体目标类型时，默认用 float64 表示数字。

选择规则可以先记住一句话：结构稳定就直接解码到 int64、uint64 或 float64；结构动态但要保留数字字面量，就用 Decoder.UseNumber()；如果数字只负责展示，才考虑字符串化。

官方资料：https://pkg.go.dev/encoding/json

一、先看精度丢失发生在哪里

标准库把 JSON 解码到空接口时，会把布尔值放成 bool，字符串放成 string，数组放成 []any，对象放成 map[string]any，数字则默认放成 float64。因此下面的代码即使没有返回错误，也已经选择了浮点表示。

package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	var payload map[string]any
	// 这里的目标是动态对象，数字会按标准库默认规则进入 float64。
	err := json.Unmarshal([]byte(`{"order_id":9007199254740993}`), &payload)
	if err != nil {
		panic(err)
	}
	// 先打印动态值的实际类型，再决定是否需要调整解码策略。
	fmt.Printf("%T %v\n", payload["order_id"], payload["order_id"])
}

问题在于二进制浮点数对所有整数并没有无限精度。接近或超过常见安全整数范围的值，可能在转成 float64 时失去低位信息；之后再转回整数，拿到的已经不是输入中的原始数字。

二、结构稳定时直接解码到目标类型

如果接口协议已经确定，最稳妥的方案不是先建一个大而全的动态对象，而是让结构体字段直接表达业务含义。订单号、数据库主键或计数器通常应使用整数类型；金额如果协议约定为小数，才使用合适的定点或浮点表示方案。

package main

import (
	"encoding/json"
	"fmt"
)

type Order struct {
	// 明确字段类型，让解码器按 int64 检查范围，而不是先经过 float64。
	OrderID int64 `json:"order_id"`
	// 数量是整数时保持整数语义，避免后续再做浮点到整数的转换。
	Quantity int64 `json:"quantity"`
}

func main() {
	var order Order
	// 目标类型明确时，超出字段范围会返回解码错误，便于在入口处处理。
	err := json.Unmarshal([]byte(`{"order_id":9007199254740993,"quantity":2}`), &order)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%d %d\n", order.OrderID, order.Quantity)
}

这种写法的价值是把错误暴露在边界处：输入不能放进 int64 时，调用方可以记录错误或返回请求失败，而不是等数据进入订单、账务或缓存逻辑后才发现比较结果异常。

三、结构动态时改用 UseNumber

有些 JSON 是扩展字段、规则配置或多版本载荷，字段名和结构无法全部提前建模。这时可以继续使用动态对象，但在创建 Decoder 后调用 UseNumber，让数字先保留为 json.Number 的文本形式。

package main

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

func decodeDynamic(data []byte) (map[string]any, error) {
	var payload map[string]any
	dec := json.NewDecoder(bytes.NewReader(data))
	// UseNumber 只改变接口字段的数字表示，不会自动选择 int64 或 float64。
	dec.UseNumber()
	if err := dec.Decode(&payload); err != nil {
		return nil, err
	}
	return payload, nil
}

func main() {
	payload, err := decodeDynamic([]byte(`{"order_id":9007199254740993}`))
	if err != nil {
		panic(err)
	}
	number, ok := payload["order_id"].(json.Number)
	if !ok {
		panic("order_id 不是 json.Number")
	}
	// 在真正需要整数的分支里显式转换，并保留转换错误。
	orderID, err := number.Int64()
	if err != nil {
		panic(err)
	}
	fmt.Println(orderID)
}

json.Number 的 String() 会返回原始数字字面量；需要整数时调用 Int64()，需要浮点计算时调用 Float64()，每个转换都应该检查错误。这样做把“保留输入”与“解释输入”拆成了两个步骤。

四、按数字用途做方案选择

类型选择取决于数字进入系统后的用途，而不是取决于字段名看起来像不像数字。结构确定时目标类型更简单；结构不确定时，UseNumber 给你留下后续判断的空间；仅用于页面展示时，保持字符串可以避免不必要的数学运算。

五、排查常见误区

UseNumber 能不能和 json.Unmarshal 一起用？

不能直接在 json.Unmarshal 上调用。它是 Decoder 的配置，需要用 json.NewDecoder 创建解码器，再调用 UseNumber。如果已经有稳定结构，仍然优先使用结构体字段。

UseNumber 会自动把数字变成 int64 吗？

不会。它只把动态接口中的数字换成 json.Number，最终调用 Int64 还是 Float64，应该由业务语义决定；转换失败时必须保留错误。

嵌套数组里的数字也会保留吗？

会，只要这些数字是通过同一个启用了 UseNumber 的解码器进入动态值，数组和嵌套对象中的数字也会以 json.Number 表示。

一句话怎么记？

能建模就建模，不能建模就先保留文本，真正计算前再做一次有错误处理的类型转换。