Go encoding/json 数字解码为什么变成 float64怎样构造最小复现

把 JSON 解码到 map[string]any 后，数字默认变成 float64，这是 encoding/json 对动态容器的既定映射，不是 JSON 文本被偷偷改写。最小复现只需要让解码目标落到 any，然后用类型断言观察它的动态类型。

如果字段结构稳定，优先解码到结构体；如果对象字段不固定但又不能马上把数字定成浮点数，就用 Decoder.UseNumber() 保留为 json.Number，最后根据业务规则显式转成整数或浮点数。

关键词：Go、encoding/json、float64、json.Number、UseNumber、类型断言

先把 float64 现象固定下来

排查时先不要急着改断言。下面的代码把 JSON 解码到 map[string]any，整数和小数都从接口中取出，再打印动态类型。代码块中的输出是理解现象的示意，不代表本文在本机执行过的截图。

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    // 使用 any 作为目标，复现开放 JSON 对象的默认类型映射。
    payload := []byte(`{"count": 3, "ratio": 1.25}`)
    var doc map[string]any
    if err := json.Unmarshal(payload, &doc); err != nil {
        // 保留解码错误，避免把格式问题误判为类型问题。
        panic(err)
    }

    // %T 观察接口中实际保存的动态类型，%v 观察对应值。
    fmt.Printf("count: %T %v\n", doc["count"], doc["count"])
    fmt.Printf("ratio: %T %v\n", doc["ratio"], doc["ratio"])
}

你会看到两个值的动态类型都属于 float64。因此下面的断言会失败：

// 这里的断言与 encoding/json 解码到 any 的默认映射不匹配。
count := doc["count"].(int)

真正需要确认的是“解码目标是什么”。同一段 JSON 如果目标是结构体字段 int64，结果就不会先经过 float64 这条动态容器路径。

为什么动态容器默认选择 float64

JSON 自身只有一个“数字”概念，而 Go 的 any 需要在运行时选择具体类型。encoding/json 的默认规则把 JSON 对象映射为 map[string]any，数组映射为 []any，数字映射为 float64，布尔值和字符串则分别映射为 bool 与 string。

这套规则适合快速读取未知结构，但它也意味着两个边界：第一，类型断言必须断言为 float64；第二，特别大的整数如果先进入浮点表示，不能把它当作精确整数继续使用。问题的根因不是 fmt.Printf 的格式，也不是 JSON 中把整数写成了小数。

字段长期稳定时，直接给出目标结构更清楚：

type Envelope struct {
    Count int64   `json:"count"`
    Ratio float64 `json:"ratio"`
}

var env Envelope
if err := json.Unmarshal(payload, &env); err != nil {
    // 结构化解码让数值类型由字段声明决定，错误在入口处返回。
    returnWithError(err)
}

// env.Count 是 int64，env.Ratio 是 float64，不需要从 any 做断言。
_ = env

示例中的 returnWithError 代表业务函数自己的错误处理，不是标准库 API。实际项目里应把错误返回给调用方或记录到合适的日志边界。

开放字段怎样保留数字语义

如果顶层字段或嵌套结构不固定，结构体未必能覆盖全部输入。这时可以使用 Decoder，在解码前调用 UseNumber()。数字会以 json.Number 保留其文本形式，随后由业务代码决定转成整数还是浮点数。

package main

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

func decodeNumber(payload []byte) error {
    // Decoder 适合从字节流读取 JSON，UseNumber 避免数字直接落成 float64。
    dec := json.NewDecoder(bytes.NewReader(payload))
    dec.UseNumber()

    var doc map[string]any
    if err := dec.Decode(&doc); err != nil {
        // 解码失败要原样返回，不能用零值掩盖输入错误。
        return err
    }

    number, ok := doc["count"].(json.Number)
    if !ok {
        // 字段缺失或类型不符时交给调用方判断是否可接受。
        return fmt.Errorf("count 不是 json.Number")
    }
    count, err := number.Int64()
    if err != nil {
        // Int64 会拒绝带小数或超出 int64 范围的文本。
        return fmt.Errorf("count 不是有效整数: %w", err)
    }
    fmt.Println(count)
    return nil
}

UseNumber 不是“自动把所有数字变成 int64”。它只是把默认的浮点落点换成 json.Number，精确的目标类型仍要由 Int64() 或 Float64() 的调用者决定，并处理转换错误。

把三类常见误判分开

类型断言失败：先检查目标是不是 map[string]any 或 []any。若是，默认数字断言应从 int 改为 float64，或者改用前面的结构体/UseNumber 方案。

整数精度风险：不要把可能超过浮点精确范围的业务编号、订单号、雪花 ID 当作普通数值计算。若协议允许，把它定义成 JSON 字符串；若必须保留数字文本，使用 json.Number 并在边界处转成合适的整数类型。

未知字段与已知字段混杂：已知字段放入结构体，扩展字段可以单独保留为 json.RawMessage 或在受控位置使用 UseNumber。不要为了一个动态字段让整份文档都退回到无类型的 map[string]any。

可以用下面这张速查表做选择：

相关问题

为什么 JSON 里的 3 不是 Go 的 int？

因为它被解码到了 any。在这个动态容器映射中，encoding/json 默认用 float64 表示 JSON 数字。

UseNumber 能解决大整数精度问题吗？

它能避免数字一开始就落到浮点表示，但最终仍需选择合适的整数类型，并处理超范围和非法格式错误；如果业务编号不参与计算，字符串通常更直接。