json/v2 解码数字时如何避免默认转成 float64

encoding/json/v2 把 JSON 解码到空的 any 或 map[string]any 时，数字默认仍使用 float64。要避免精度丢失，优先把已知字段声明成 int64、uint64 等具体类型；只有结构确实动态时，才用 WithUnmarshalers 将数字保留为 jsontext.Value，再按业务规则显式转换。

Go 1.27 已正式提供 encoding/json/v2 和 encoding/json/jsontext。如果维护的是 Go 1.25–1.26 实验期代码，还要考虑当时的 GOEXPERIMENT=jsonv2 构建方式与 API 变化。

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

为什么 any 仍然得到 float64

JSON 只有“number”一种数值类别，并不携带“这是 int64、uint64 还是十进制定点数”的 Go 类型信息。当目标是空的 any 时，解码器必须选择一个默认承载类型，v2 与 v1 一样选择 float64。这不是 v2 解码失败，而是目标类型没有给出更精确的约束。

float64 能精确表示的整数范围有限。例如 9007199254740993 已超过连续精确整数区间，把它先放进 float64 再转回整数，原值可能已经改变。高精度小数也会因为二进制浮点表示而发生舍入。

判断是否需要处理的关键不是“输入看起来有没有小数点”，而是目标是否为动态接口。解码到具体整数类型时，v2 会按该类型解析并检查范围；解码到空接口时才会自动选择 float64。

最小配方：已知字段直接声明整数类型

接口结构稳定时，不要先解码到 map[string]any 再做类型断言。直接声明业务结构体，既能保留整数精度，也能让超范围、类型不匹配等问题在解码阶段返回错误。

package main

import (
    "fmt"
    "log"

    "encoding/json/v2"
)

type Payment struct {
    // 订单 ID 是无符号整数，不经过 float64 中转
    OrderID uint64 `json:"order_id"`

    // 数量允许负值时可明确使用 int64
    Delta int64 `json:"delta"`
}

func main() {
    input := []byte(`{"order_id":9007199254740993,"delta":-7}`)

    var p Payment
    // 目标字段提供了明确类型，解码器会按 uint64 和 int64 解析
    if err := json.Unmarshal(input, &p); err != nil {
        log.Fatal(err)
    }

    // 这里得到的是精确整数，而不是从 float64 反向转换
    fmt.Printf("order=%d delta=%d\n", p.OrderID, p.Delta)
}

这个写法也适合 map[string]uint64、[]int64 等容器。只要目标元素类型明确，JSON number 就不会先变成 float64。如果输入带小数或超出范围，应该把错误返回给调用方，而不是静默截断。

动态结构里保留原始数字

配置中心、Webhook、审计事件等场景往往无法预先定义所有字段，只能解码到 any。v2 没有照搬 v1 Decoder.UseNumber 的调用方式，而是允许通过 WithUnmarshalers 覆盖特定目标类型的解码行为。

核心思路是拦截所有解码到 any 的位置：如果下一个 JSON 值是 number，就先把接口预填充为 jsontext.Value。随后返回 errors.ErrUnsupported，让 v2 的默认逻辑继续把当前值解码到这个具体类型。jsontext.Value 保存原始 JSON 文本，因此不会发生浮点转换。

package exactjson

import (
    "errors"

    "encoding/json/jsontext"
    "encoding/json/v2"
)

// ExactNumbers 返回一个 v2 选项，只改变 any 中 JSON 数字的承载类型。
func ExactNumbers() json.Options {
    return json.WithUnmarshalers(
        json.UnmarshalFromFunc(func(dec *jsontext.Decoder, dst *any) error {
            // PeekKind 对 JSON number 返回 '0'，此处不消费输入。
            if dec.PeekKind() == '0' {
                // 预填充具体类型，让后续默认逻辑写入原始数字文本。
                *dst = jsontext.Value(nil)
            }

            // 回退到 v2 默认解码；非数字仍使用 bool、string、map 或 slice。
            return errors.ErrUnsupported
        }),
    )
}

这个选项会递归作用于动态对象和数组中的 any。字符串仍是 string，布尔值仍是 bool，对象与数组仍按动态容器处理；只有 number 改用 jsontext.Value 保存。

按业务类型做最后一次转换

保留原始文本只是第一步。JSON 本身不知道 order_id 应该是无符号整数，还是一个允许指数形式的高精度量。最终转换必须放在业务边界完成，并对格式与范围报错。

package main

import (
    "errors"
    "fmt"
    "log"
    "math/big"
    "strconv"

    "encoding/json/jsontext"
    "encoding/json/v2"
)

var keepRawNumbers = json.WithUnmarshalers(
    json.UnmarshalFromFunc(func(dec *jsontext.Decoder, dst *any) error {
        // 仅为 JSON number 指定 jsontext.Value，其他类型继续走默认映射。
        if dec.PeekKind() == '0' {
            *dst = jsontext.Value(nil)
        }
        return errors.ErrUnsupported
    }),
)

func rawNumber(obj map[string]any, key string) (jsontext.Value, error) {
    // 字段缺失与类型错误分别返回，避免把零值当成有效结果。
    value, ok := obj[key]
    if !ok {
        return nil, fmt.Errorf("字段 %q 不存在", key)
    }
    raw, ok := value.(jsontext.Value)
    if !ok {
        return nil, fmt.Errorf("字段 %q 不是 JSON 数字", key)
    }
    return raw, nil
}

func main() {
    input := []byte(`{
        "order_id": 9007199254740993,
        "ratio": 3.141592653589793238462643383279
    }`)

    var doc map[string]any
    // 选项会把动态结构中的数字保留为原始 JSON 文本。
    if err := json.Unmarshal(input, &doc, keepRawNumbers); err != nil {
        log.Fatal(err)
    }

    idRaw, err := rawNumber(doc, "order_id")
    if err != nil {
        log.Fatal(err)
    }
    // ID 不接受小数或指数形式，并检查 uint64 范围。
    id, err := strconv.ParseUint(string(idRaw), 10, 64)
    if err != nil {
        log.Fatalf("order_id 无效: %v", err)
    }

    ratioRaw, err := rawNumber(doc, "ratio")
    if err != nil {
        log.Fatal(err)
    }
    // 用 256 位精度解析高精度小数，避免 float64 的固定精度限制。
    ratio, _, err := big.ParseFloat(string(ratioRaw), 10, 256, big.ToNearestEven)
    if err != nil {
        log.Fatalf("ratio 无效: %v", err)
    }

    // Text 使用十进制形式输出，便于检查精度是否按业务要求保留。
    fmt.Printf("order_id=%d ratio=%s\n", id, ratio.Text('g', -1))
}

如果整数可能超过 uint64，可用 new(big.Int).SetString(string(raw), 10)；如果金额必须固定小数位，通常应使用业务自定义 decimal 类型，并在转换时验证小数位数。不要把所有数字都无条件转换为大数，否则会把类型判断推迟到更难维护的位置。

几个常见误区

json:",string" 适合解决跨语言系统无法精确表示 64 位整数的问题，但它改变了线上 JSON 形态：数字会放在字符串中。本文的场景是输入仍为标准 JSON number，只在 Go 的动态目标中避免默认进入 float64，两者不要混用。

完整片段该怎么取舍

最短决策可以归纳为三条：

1. 字段已知：直接使用结构体、map[string]uint64 或其他具体数值类型。
2. 结构动态但数字需要保真：通过 WithUnmarshalers 将 number 保留为 jsontext.Value。
3. 进入业务层时：按字段含义调用 strconv、math/big 或自定义 decimal 解析器，并处理格式与范围错误。

不要用“先变成 float64、之后再猜回原类型”的方式修补，因为丢失的精度无法恢复。更稳妥的边界是：解码阶段保留信息，业务阶段决定类型。

相关问题

json/v2 是否提供与 Decoder.UseNumber 完全相同的方法？

v2 更倾向于通过 options 和类型专用 unmarshalers 定制行为。动态数字保真可使用官方文档展示的 WithUnmarshalers 模式，而不是寻找同名方法。

jsontext.Value 是最终业务类型吗？

通常不是。它适合在解码边界保留原始 JSON 值。进入订单、金额、计量等业务逻辑前，仍应转换为明确类型并验证范围。

Go 1.25 的示例能直接放到 Go 1.27 吗？

不应盲目复制实验期代码。Go 1.27 已将两个包正式加入标准库，实验期间部分选项、标签和名称发生过调整；迁移时应以当前包文档和迁移指南为准。

只处理整数，还需要 math/big 吗？

只要值确定落在 int64 或 uint64 范围内，使用 strconv.ParseInt 或 ParseUint 更直接。只有范围超出原生整数，或小数精度要求更高时，才需要 math/big 或专用十进制类型。