JSON 数字错误

我在处理一批带有业务编号的 JSON 时遇到过一个很容易误判的错误：输入里明明是整数，代码却在转换阶段报错；如果先把它解码成 float64，大整数还可能已经悄悄丢掉精度。这个问题的关键不是“怎样把错误屏蔽掉”，而是要在第一次解码时就保留数字字面量。

更稳妥的做法是给 json.Decoder 调用 UseNumber()，让接口值中的数字变成 json.Number。随后用 Int64() 判断它是不是范围内的整数；转换失败时，直接用 String() 取回原始数字文本，连同错误一起交给调用方决定。

先把 JSON 数字留在文本边界内

如果目标类型是明确的 int64 字段，结构体解码通常已经足够；真正容易踩坑的是“字段形状不固定”，于是使用 map[string]any 或 []any 接收数据。此时默认解码会把 JSON 数字放进 float64，原始文本不再是可靠的存储位置。

例如订单号、外部系统流水号可能看起来像数字，却不一定需要参与浮点运算。先让 Decoder 使用 json.Number，可以把“保留原文”和“是否能转成整数”拆成两个判断。

package main

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

func main() {
	input := `{"id": 9007199254740993, "ratio": 12.5}`
	dec := json.NewDecoder(strings.NewReader(input))
	// 让 interface{} 中的 JSON 数字保留为 json.Number，而不是先变成 float64。
	dec.UseNumber()

	var payload map[string]any
	if err := dec.Decode(&payload); err != nil {
		// 输入语法错误要直接返回，不能把失败字段当成空值继续处理。
		panic(err)
	}

	for key, raw := range payload {
		if number, ok := raw.(json.Number); ok {
			fmt.Printf("%s: %s\n", key, number.String())
		}
	}
}

这里的 id 会以 json.Number 保存，String() 返回的是数字字面量；它还没有被强行解释成某种业务数值。要注意，UseNumber() 只负责保留形式，后面的类型判断仍然需要代码明确完成。

用 Int64 判断“能不能当整数”

json.Number.Int64() 适合做一个窄而清晰的门禁：只有输入文本表示一个在有符号 64 位范围内的整数时，才把它交给整数逻辑。带小数部分的数字、使用指数后超出范围的数字，以及本身超出范围的整数，都会返回错误。

实际代码里，不要只写一个“转换失败”的日志就丢掉数字。错误对象告诉你转换没有完成，而 number.String() 让日志、补偿消息或人工复核仍然能看到输入到底是什么。

Int64 失败时不要丢掉 Number

我更愿意把解析结果设计成“成功值 + 原文 + 错误”三者中的明确分支：成功时继续使用 int64；失败时保留 json.Number 的原文，再根据调用场景决定是拒绝请求、走小数处理，还是把值交给上层业务。

package main

import (
	"encoding/json"
	"fmt"
)

type integerResult struct {
	Value int64
	Raw   string
	Err   error
}

func parseInteger(number json.Number) integerResult {
	value, err := number.Int64()
	if err != nil {
		// 失败时保留原始字面量，避免错误处理阶段只剩一个模糊的空值。
		return integerResult{Raw: number.String(), Err: err}
	}
	// 成功分支仍保留 Raw，便于审计或需要原文的下游逻辑。
	return integerResult{Value: value, Raw: number.String()}
}

func main() {
	for _, raw := range []json.Number{"42", "12.5", "9223372036854775808"} {
		result := parseInteger(raw)
		if result.Err != nil {
			fmt.Printf("保留=%s，原因=%v\n", result.Raw, result.Err)
			continue
		}
		fmt.Printf("整数=%d，原文=%s\n", result.Value, result.Raw)
	}
}

这个返回结构故意不把失败值改成 0。因为 0 既可能是合法输入，也可能是调用方误解失败结果后的默认值；将 Raw 和 Err 一起返回，才能让上层做出可追踪的决定。

把错误处理放在转换边界，而不是日志末尾

如果数字字段是接口契约中的必填整数，收到 Int64() 错误后可以返回参数错误，并在日志中记录 Raw。如果字段允许小数，则不要再次尝试把它变成 float64 来“绕过”错误，而应明确切换到小数类型或十进制字符串方案。对订单号、金额字符串这类标识性字段，原文通常比近似值更重要。

还有一个边界：json.Number 只解决数字文本保留，不会自动识别业务单位、正负号策略或小数精度规则。那些规则应由领域代码单独决定，避免把标准库的语法转换错误误当成业务校验结论。

常见问题

为什么不能先把 JSON 数字解码成 float64 再转 int64？

因为转成 float64 后，较大的整数可能已经无法逐位表示，之后再转回 int64 只能得到被改变过的值。需要保留输入时，应先调用 UseNumber()。

UseNumber 会让所有数字都自动变成 int64 吗？

不会。它让接口值里的数字保持为 json.Number，具体转成 Int64、Float64 或继续作为文本，都由调用方决定。

Int64 失败后还能知道原始输入吗？

可以。只要没有先丢给 float64，json.Number.String() 就能返回它保存的数字字面量；同时保留返回的错误，才能区分格式不适合整数还是范围不足。

直接把字段声明成 json.Number 可以吗？

可以，但仍要在业务边界调用 Int64() 或其他转换方法。字段类型解决“如何保存”，不替代“这个字段是否必须是范围内整数”的业务判断。

这类 JSON 数字错误的处理重点只有一句话：先保住原始字面量，再做窄范围转换。这样即使整数判断失败，调用方仍有足够信息进行拒绝、补偿或人工复核。