Go JSON 数字怎么避免解码成 float64

用 encoding/json 把不确定结构解码到 map[string]any 时，JSON 数字默认会落成 float64。如果字段是订单号、雪花 ID 或超过安全精度的计数值，后续再转整数可能已经丢失原始数字。解决办法是使用 json.Decoder.UseNumber()，先保留字面量，再由业务代码决定如何转换。

为什么 map[string]any 的数字会变成 float64

默认解码规则是按目标类型决定结果：布尔值为 bool，字符串为 string，对象为 map[string]any，数组为 []any，数字则为 float64。因此下面的 JSON 并没有告诉解码器 id 是哪一种整数：

var payload map[string]any
err := json.Unmarshal([]byte(`{"id":9007199254740993,"ratio":0.875}`), &payload)
if err != nil {
	// 输入格式错误时立即返回，避免继续使用不完整数据。
	return err
}
fmt.Printf("%T %v\n", payload["id"], payload["id"])

问题不在 JSON 本身，而在目标容器是动态的。float64 的有效整数精度有限，先经过它再转成 int64，并不能恢复原始字面量。若接口契约固定，直接定义结构体字段通常更简单；只有字段集合或类型确实不稳定时，才需要保留数字。

UseNumber 把原始数字文本留下来

UseNumber 只影响 interface{} 中的数字。它会让解码结果变成 json.Number，其底层是字符串形式的 JSON 数字，因此可以等到知道业务含义后再转换。

dec := json.NewDecoder(strings.NewReader(`{"id":9007199254740993,"ratio":0.875}`))
dec.UseNumber()

var payload map[string]any
if err := dec.Decode(&payload); err != nil {
	// 解码失败时不继续读取动态字段。
	return err
}

id, ok := payload["id"].(json.Number)
if !ok {
	return fmt.Errorf("id 不是 json.Number")
}
fmt.Println(id.String()) // 保留 9007199254740993 的文本

调用顺序很重要：必须在 Decode 之前设置 UseNumber。它也不会影响已经明确声明为 int64、uint64 或 float64 的结构体字段。

根据业务边界把 Number 转成整数或小数

拿到 json.Number 后，转换方法就是一项业务决策。整数型 ID、数量和时间戳可以调用 Int64()，金额或比例若允许浮点近似才调用 Float64()；需要原样转发或交给高精度库时保留 String()。

func readInt64(v any, field string) (int64, error) {
	n, ok := v.(json.Number)
	if !ok {
		return 0, fmt.Errorf("%s 类型不是 json.Number", field)
	}
	value, err := n.Int64()
	if err != nil {
		// 溢出或小数输入必须失败，不能用 Float64 绕过边界。
		return 0, fmt.Errorf("%s 不是有效 int64: %w", field, err)
	}
	return value, nil
}

结构体字段与字符串数字怎么选

如果接口字段稳定，优先用结构体，让解码器直接做类型检查：

type Response struct {
	ID    int64  `json:"id"`
	Ratio string `json:"ratio"` // 需要精确保存时让上游传字符串
}

var response Response
if err := json.Unmarshal(data, &response); err != nil {
	// 类型不匹配或整数溢出会返回错误，交给接口层处理。
	return err
}

动态字段才使用 UseNumber；而跨语言接口中的金额、超长 ID 如果可以协商，直接使用 JSON 字符串往往更清楚。不要为了“避免 float64”把所有数字都变成字符串，否则排序、范围判断和校验会被推迟到每个调用方。

常见问题

UseNumber 能保证任意大整数都能转成 int64 吗？

不能。它只保留字面量；超过 int64 范围的值应保留字符串，或交给支持大整数的库。

json.Number 是不是已经完成了数值校验？

它表示合法 JSON 数字的文本，但具体转换仍可能因整数溢出或小数格式不合适而失败，必须检查返回的 error。

只调用 json.Unmarshal 能使用 UseNumber 吗？

不能。UseNumber 是 Decoder 的设置；需要先创建 json.NewDecoder，再调用它后执行 Decode。

官方参考：Decoder.UseNumber、json.Number。