Go JSONUseNumber 后转换失败如何定位字段

遇到 json.Decoder.UseNumber() 之后转换失败，先不要把问题归咎于 JSON 或 UseNumber 本身。这个方法只负责让解码到 interface{} 的数字保留为 json.Number，真正的类型选择发生在后面的 Int64()、Float64() 或业务转换代码里。排查的关键是保留原始数字字面量，再把错误映射回字段路径。

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

最稳妥的处理顺序是：先打印或记录 json.Number.String()，再根据字段语义选择整数或浮点转换；如果解码阶段本身报错，则优先读取 UnmarshalTypeError.Field、Struct、Value 和 Offset，不要只看错误字符串。

• UseNumber 不会把数字自动转换成任意整数类型。
• json.Number 保存的是 JSON 数字字面量，Int64 和 Float64 都可能返回错误。
• 结构体字段解码失败时，UnmarshalTypeError 能提供字段路径和输入偏移。
• 超过 int64 的业务标识符不要为了“转成功”强行变成浮点数。

先确认 UseNumber 改变了什么

默认情况下，使用 Decoder 解码到 map[string]any 或其他空接口时，JSON 数字通常会落成 float64。调用 UseNumber 后，数字改为 json.Number。官方文档对它的定义很明确：它代表一个 JSON number literal，底层是字符串语义，而不是已经完成校验的业务整数。

因此，下面两步是不同责任：第一步是把输入保留下来，第二步才是判断它是否适合当前字段。

package main

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

func readAmount() error {
    input := `{"amount":9007199254740993,"ratio":1.25}`
    dec := json.NewDecoder(strings.NewReader(input))
    dec.UseNumber() // 让 interface 中的数字保留为 json.Number，避免先落成 float64。

    var payload map[string]any
    if err := dec.Decode(&payload); err != nil {
        return fmt.Errorf("decode JSON: %w", err) // 解码错误和后续类型转换错误要分开记录。
    }

    amount, ok := payload["amount"].(json.Number)
    if !ok {
        return fmt.Errorf("amount is %T, want json.Number", payload["amount"])
    }
    fmt.Println("原始字面量:", amount.String()) // 先保留证据，再决定用 Int64 还是 Float64。
    return nil
}

这里的 9007199254740993 只是为了说明为什么不要在不清楚字段语义时先转 float64：浮点类型的有效精度与整数范围不是同一件事。UseNumber 能避免过早丢失字面量，但它不会替你决定这个字段应该是什么类型。

从原始字面量判断转换为什么失败

json.Number.String() 返回原始数字文本；Int64() 适合明确要求有符号 64 位整数的字段，Float64() 适合业务允许浮点近似的字段。两者都会把解析失败作为错误返回，所以必须检查错误值。

func convertNumber(n json.Number) (int64, error) {
    raw := n.String()
    value, err := n.Int64()
    if err != nil {
        // raw 能区分小数、科学计数法、空值或超出 int64 的数字。
        return 0, fmt.Errorf("number %q cannot be int64: %w", raw, err)
    }
    return value, nil
}

func convertRatio(n json.Number) (float64, error) {
    raw := n.String()
    value, err := n.Float64()
    if err != nil {
        // 浮点转换也可能因非法字面量或范围问题失败，不能忽略 err。
        return 0, fmt.Errorf("number %q cannot be float64: %w", raw, err)
    }
    return value, nil
}

常见现象可以这样分组：

用 UnmarshalTypeError 定位具体字段

如果 JSON 直接解码到结构体，失败可能发生在转换成目标字段的阶段。例如接口把 retry 传成字符串，而 Go 结构体要求 int64。这时不要只用 fmt.Println(err) 保存一行文本，可以尝试提取 *json.UnmarshalTypeError。

type Request struct {
    Count int64 `json:"count"`
    Meta  struct {
        Retry int64 `json:"retry"`
    } `json:"meta"`
}

func decodeRequest(data []byte) (*Request, error) {
    var req Request
    if err := json.Unmarshal(data, &req); err != nil {
        var typeErr *json.UnmarshalTypeError
        if errors.As(err, &typeErr) {
            // Field 是从根对象到出错字段的路径，Offset 可用于定位原始输入位置。
            return nil, fmt.Errorf(
                "field=%q struct=%q value=%q offset=%d: %w",
                typeErr.Field, typeErr.Struct, typeErr.Value, typeErr.Offset, err,
            )
        }
        return nil, fmt.Errorf("decode request: %w", err) // 语法错误等其他错误保留原始类型。
    }
    return &req, nil
}

Field 是最有用的定位信息，Struct 表示根结构体名称，Value 描述收到的 JSON 类型，Offset 是读取到错误附近的字节偏移。它们帮助你区分“字段值不符合协议”和“JSON 语法已经损坏”这两类问题。

按字段语义选择修复方案

修复时不要只追求“转换成功”，先确认字段在协议中的含义：

如果上游把数字包在字符串中，先确认这是协议设计还是数据污染。可以为该字段实现自定义 UnmarshalJSON，但要把允许的格式、空字符串和溢出行为写清楚；不要为了兼容一个异常样本，把所有数字字段都改成 any。

一张表收敛排障路径

排障日志可以记录字段路径、原始字面量的脱敏版本、目标类型和偏移，但要避免把整个请求体直接写入日志，尤其是请求中还可能包含凭据或个人数据。

常见问题

UseNumber 会让所有数字都变成 json.Number 吗？

它影响的是解码到空接口时的数字表示。已经映射到明确结构体字段的值，仍然会按照目标字段类型处理。

为什么 json.Number 还是转换失败？

因为它只是 JSON 数字字面量的保留形式。Int64 需要整数且不能溢出，Float64 也需要合法且可表示的数字。

能不能所有数字都用 Float64？

不建议。浮点数适合允许近似的测量或比例，不适合需要无损比较的订单号、账务标识或其他长整数编号。

Field 为空是不是说明没有错误字段？

不一定。错误可能来自顶层值、语法或其他解码阶段。先判断错误是否能提取为 UnmarshalTypeError，再结合 Value、Type 和 Offset 分析。