Go json.Number 读取大整数时怎样避免浮点精度丢失

Go 读取 JSON 时，真正容易出错的不是“大整数不能解析”，而是动态 JSON 默认把数字放进了 float64。例如订单号 9007199254740993 进入 interface{} 后，数值可能已经改变。解决办法是让解码器使用 json.Number 保留数字字面量，之后再根据业务范围选择 Int64()、math/big 或字符串。

只要 JSON 数字会先进入 map[string]any、[]any 或其他动态容器，就先调用 Decoder.UseNumber()；读取整数时检查 Int64() 的错误，不要把 json.Number 直接转成 float64。

动态 JSON 为什么要先保留数字字面量

encoding/json 解码到 interface{} 时，JSON 数字默认对应 float64。这对普通金额比例、计数值通常没有感觉，但超过浮点数能精确表达的范围后，尾数就可能被改写。问题发生在“动态解码”这一步，而不是 JSON 本身不能承载大整数。

当结构已经确定时，直接让字段承担约束更简单：

type Event struct {
	// 已知字段直接使用整数类型，让解码器在边界处返回错误。
	Sequence int64 `json:"sequence"`
}

只有字段不固定、需要遍历未知对象时，才使用 Decoder.UseNumber()：

package main

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

func readNumber() error {
	// UseNumber 让 interface{} 中的数字保留为 json.Number。
	dec := json.NewDecoder(strings.NewReader(`{"id":9007199254740993}`))
	dec.UseNumber()

	var payload map[string]any
	if err := dec.Decode(&payload); err != nil {
		// 解码错误必须向上返回，不能拿半成品继续计算。
		return err
	}

	n, ok := payload["id"].(json.Number)
	if !ok {
		return fmt.Errorf("id 不是 JSON number")
	}
	// String 返回数字字面量；这里不会先经过 float64。
	fmt.Println(n.String())
	return nil
}

Int64 能处理到哪里，超出范围怎么办

json.Number 本质上保存的是 JSON 数字字面量。String() 适合审计、转发和再次序列化；Int64() 则会尝试把它变成 Go 的 int64，格式不对、带小数或超出范围时都应该检查返回的错误。

超过 int64 时，可以把原字面量交给大整数类型；带小数的业务则要先明确“精确分数”还是“展示文本”，不要把两者混成一个浮点数：

package main

import (
	"fmt"
	"math/big"
)

func parseExact(text string) error {
	// SetString 的第二个返回值表示是否成功，失败时不能继续使用结果。
	integer, ok := new(big.Int).SetString(text, 10)
	if !ok {
		return fmt.Errorf("不是十进制整数: %s", text)
	}
	fmt.Println(integer.String())
	return nil
}

常见误区和落地检查清单

第一，不要看到“大整数”就把所有结构体字段改成字符串；稳定的整数协议用 int64 更能表达约束。第二，不要只写 UseNumber() 而忽略后续转换，json.Number 仍然需要业务决定如何解释。第三，转发未知字段时优先保留 String() 的文本，避免一次读取就损坏原值。

• 动态容器是否在解码前调用了 UseNumber()？
• 调用 Int64() 后是否检查了 error？
• 超大整数是否需要 math/big.Int，小数是否需要 big.Rat？
• 测试数据是否覆盖负数、空字符串、带小数和超范围整数？

相关问题

json.Unmarshal 到结构体的 int64 会经过 float64 吗？

不会。字段类型明确为 int64 时，解码器会按该字段类型解析；浮点精度问题主要出现在数字先进入 interface{} 的场景。

json.Number.String() 会验证数字是否合法完整吗？

它返回保存的字面量，不承担业务类型转换。需要整数约束时继续调用 Int64()，需要大整数时交给 big.Int 并检查解析结果。

可以直接调用 json.Number.Float64() 吗？

只有业务明确接受近似值时才适合。订单号、外部 ID、金额最小单位等要求精确相等的字段，不应把它们转成浮点数。

为什么不把所有 JSON 数字都当字符串？

字符串能保留文本，但会把数值范围、正负号和计算语义交给每个调用方。稳定协议优先使用明确的整数类型，动态协议再按字段用途选择 json.Number、大数或文本。