Go json.Number 怎样先校验数字文本再选择 Int64 或 Float64

我在处理一批接口数据时遇到过一个很隐蔽的数字问题：JSON 里明明是一个很大的整数，解码到 map[string]any 后却变成了 float64，再次转回文本时末尾已经不一样了。要保留数字字面量，入口处应使用 Decoder.UseNumber；拿到 json.Number 后，先校验文本和形态，再决定走 Int64 还是 Float64。

官方文档：https://pkg.go.dev/encoding/json#Number

数字转换不要从目标类型倒推。先保留 json.Number 的原始文本，确认它是合法 JSON 数字，再根据是否含小数或指数、是否落在 int64 范围内选择转换；有精度要求时保留原文，别把 Float64 当作无损中间层。

默认解码为什么会让大整数变成 float64

当 JSON 数字进入接口值、map[string]any 或 []any 时，encoding/json 的默认行为会把它解码为 float64。这对普通金额比例、计数和小范围计算很方便，但二进制浮点数不是任意长度整数的无损容器，超过可精确表达范围的编号、时间戳或外部流水号就可能发生变化。

json.Number 本质上是保存 JSON 数字字面量的字符串类型，它提供 String、Int64 和 Float64 方法。对接口值使用 UseNumber 后，解码器会把数字留在这个类型里，后续代码可以根据业务需求再决定是否落成具体数值。

先把 JSON 数字留在文本形态

入口函数可以把读取器交给 json.NewDecoder，紧接着调用 UseNumber。这样示例中的 id 不会在第一次解码时被迫转换成 float64。UseNumber 只改变数字在接口值中的表示方式，不会自动替你决定它最终应该是整数、浮点数还是字符串。

package numbers

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

func decodeNumbers(r io.Reader) (map[string]any, error) {
    dec := json.NewDecoder(r)
    // 保留接口值中的 JSON 数字文本，避免默认落成 float64。
    dec.UseNumber()

    var value map[string]any
    if err := dec.Decode(&value); err != nil {
        // 解码错误要原样包装，便于上层定位输入问题。
        return nil, fmt.Errorf("decode JSON: %w", err)
    }
    return value, nil
}

如果目标是一个明确的结构体字段，直接把字段声明成 json.Number 也可以；如果数据结构是动态的，UseNumber 更适合在不牺牲原文的前提下先完成外层解析。这里的“保留”不是永久保证业务精度，而是把决定权推迟到真正知道字段语义的地方。

转换前先校验文本和数字形态

由标准 JSON 解码器产生的 json.Number 已经来自合法 JSON 文本，但函数参数可能来自配置、测试夹具或其他自定义边界，因此通用转换函数仍可以先调用 json.Valid。单独校验能排除空字符串、前导零和多余字符，之后再用小范围的格式判断选择路径。

func numberKind(n json.Number) (string, error) {
    text := n.String()
    // json.Valid 检查整个数字字面量，而不是只检查其中一段。
    if !json.Valid([]byte(text)) {
        return "", fmt.Errorf("invalid JSON number %q", text)
    }
    // 小数点或指数意味着它不能直接按 int64 解释。
    if strings.ContainsAny(text, ".eE") {
        return "float", nil
    }
    return "int", nil
}

上面的函数需要额外导入 strings。格式判断只负责选择候选路径，不能替代转换本身：整数文本仍可能超出 int64 范围，浮点文本也可能在转换时发生舍入。换句话说，json.Valid 通过不等于数值一定适合目标类型。

Int64 和 Float64 要由文本形态决定

整数路径优先调用 Int64，它会在无法按有符号 64 位整数表示时返回错误；带小数点或指数的数字走 Float64，但调用方要接受浮点表示的精度边界。对订单号、雪花 ID、银行流水号这类值，即使 Float64 返回了 nil，也不能据此认为它适合做精确标识。

package numbers

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

type ParsedNumber struct {
    Raw   string
    Int   *int64
    Float *float64
}

func parseNumber(n json.Number) (ParsedNumber, error) {
    raw := n.String()
    // 先确认原文是完整合法的 JSON 数字，再进入类型转换。
    if !json.Valid([]byte(raw)) {
        return ParsedNumber{}, fmt.Errorf("invalid JSON number %q", raw)
    }

    if strings.ContainsAny(raw, ".eE") {
        value, err := n.Float64()
        if err != nil {
            // 保留原始文本，错误中不要只留下一个笼统的转换失败。
            return ParsedNumber{}, fmt.Errorf("parse float %q: %w", raw, err)
        }
        return ParsedNumber{Raw: raw, Float: &value}, nil
    }

    value, err := n.Int64()
    if err != nil {
        // strconv 的错误可以帮助区分语法错误和整数范围错误。
        var numErr *strconv.NumError
        if errors.As(err, &numErr) {
            return ParsedNumber{}, fmt.Errorf("parse integer %q: %w", raw, err)
        }
        return ParsedNumber{}, fmt.Errorf("parse integer %q: %w", raw, err)
    }
    return ParsedNumber{Raw: raw, Int: &value}, nil
}

这个示例还需要导入 errors；为了让文章聚焦于分流，错误类型分支写得比较保守。生产代码可以把 Raw 作为日志、审计或二次解析的依据，并按业务决定超出 int64 后是否交给高精度十进制库，而不是默默降级为 float64。

把选择逻辑封装成明确的接口边界

如果每个调用点都重复判断小数点、捕获错误和解释原文，动态接口很快会出现不一致。可以让解析函数返回“原文 + 一个明确的目标值”，把精度取舍集中在一个位置。对于必须保持任意精度的字段，也可以只返回 Raw，让领域层按货币、计量或标识规则再处理。

func readID(value any) (string, error) {
    number, ok := value.(json.Number)
    if !ok {
        return "", fmt.Errorf("id is %T, want json.Number", value)
    }

    // 标识字段优先保留文本，不把它强制转换成浮点数。
    if !json.Valid([]byte(number.String())) {
        return "", fmt.Errorf("invalid id number %q", number.String())
    }
    return number.String(), nil
}

这也是一个重要的接口设计点：数值计算字段和标识字段都可能长得像 JSON 数字，但它们的结果契约不同。计算字段可以在边界清晰时落成 int64 或 float64；标识字段通常应保留字符串形式，避免任何不必要的精度转换。

批量数据和错误处理时要保留哪一层

在批量解析中，建议把“字段定位错误”“JSON 数字语法错误”“整数越界”和“浮点精度风险”分开记录。json.Number.String 负责保留输入原文，Int64 或 Float64 负责表达目标转换结果，调用方负责决定错误是否跳过当前记录、终止批次或回退到高精度方案。

• 只要数字进入接口值，就在解码入口考虑 Decoder.UseNumber。
• 先用 json.Valid 检查完整文本，再依据小数点和指数选择转换方向。
• 整数优先走 Int64 并处理范围错误；不要为了消除错误直接改用 Float64。
• 需要精确标识或审计还原时，保留 json.Number.String() 的原文。

常见问题

UseNumber 会把所有数字都变成字符串吗？不会。它把接口值中的数字保存为 json.Number，仍然保留数字语义，并提供按需转换的方法。

json.Valid 通过后就能安全调用 Float64 吗？不一定。合法 JSON 数字可能超出浮点数的精确表示范围，校验通过只代表语法合法。

整数包含指数时能不能继续调用 Int64？不要靠字符串猜测结果。指数形式通常应先按浮点路径处理；如果业务需要精确整数，应采用明确的十进制或大整数解析策略。

为什么不直接把 json.Number 转成 string？如果字段是业务标识，转成字符串是合理的；但如果字段要参与数值计算，仍需要先明确类型、范围和精度契约。