Go JSON数字默认变成float64时的类型保留方案

Go 用 encoding/json 把 JSON 解码到 map[string]any 时，数字默认落成 float64。这不是 JSON 把整数改成了小数，而是目标类型没有提供字段约束，解码器只能选择一个通用数值类型。订单号、雪花 ID、金额最小单位等数据一旦先经过浮点数，就可能在后续转换前失去原始精度。

动态 JSON 保留数字时，优先使用 json.Decoder.UseNumber()；协议稳定的接口则直接定义 int64、string 或自定义金额类型。关键是把数字转换放在业务边界，而不是让所有值先经过 float64。

默认 float64 只发生在“没有字段类型”的位置

下面的两种写法看起来都在读取数字，结果却不同。结构体字段已经告诉解码器目标是 int64；而 map[string]any 的值类型是接口，v1 encoding/json 的默认映射会把 JSON number 解成 float64。

package main

import (
    "encoding/json"
    "fmt"
)

type Event struct {
    ID int64 `json:"id"` // 固定协议直接声明整数，避免经过 float64
}

func main() {
    data := []byte(`{"id":9007199254740993}`)

    var dynamic map[string]any
    if err := json.Unmarshal(data, &dynamic); err != nil {
        panic(err) // 示例省略业务日志，生产代码应保留输入上下文
    }
    fmt.Printf("dynamic=%T %v\n", dynamic["id"], dynamic["id"])

    var fixed Event
    if err := json.Unmarshal(data, &fixed); err != nil {
        panic(err) // 固定字段由解码器直接校验 int64 范围
    }
    fmt.Printf("fixed=%T %d\n", fixed.ID, fixed.ID)
}

这里的风险点是 9007199254740993 已超过 IEEE 754 双精度能逐整数表达的安全范围。若数据会落入动态对象，不能先从 float64 转回整数来“补救”；应在解码时就阻止这一步。

UseNumber 把转换责任留在业务边界

使用 json.NewDecoder 读取流或字节缓冲区时，先调用 UseNumber，动态对象里的数字会变成 json.Number。它本质上保留了 JSON 数字字面量，可以按业务需要调用 Int64()、Float64() 或 String()。

func decodeID(data []byte) (int64, error) {
    dec := json.NewDecoder(bytes.NewReader(data))
    dec.UseNumber() // 先保留字面量，再决定整数还是其他数值

    var payload map[string]any
    if err := dec.Decode(&payload); err != nil {
        return 0, fmt.Errorf("decode JSON: %w", err) // 区分语法错误与业务转换错误
    }

    raw, ok := payload["id"].(json.Number)
    if !ok {
        return 0, fmt.Errorf("id is not a JSON number") // 缺失、字符串和 null 都不静默接受
    }
    id, err := raw.Int64()
    if err != nil {
        return 0, fmt.Errorf("id must be int64: %w", err) // 溢出或小数在这里被拒绝
    }
    return id, nil
}

示例需要补充 bytes、encoding/json 和 fmt 导入。实际项目中可以让解析函数返回业务对象，而不是把 json.Number 传遍系统。这样金额、ID 和计数器会在入口处拥有清晰的失败策略。

固定协议优先结构体，动态协议才保留 Number

如果接口字段已经确定，结构体比动态 map 更容易维护：缺字段、类型不符和超出目标范围都可以在入口暴露。只有字段由第三方扩展、键名不固定或需要透传时，才使用 map[string]any。金额不要把 json.Number 直接转成 float64 后计算；可以保留字符串，或在领域层统一换成定点整数。

数组和嵌套对象也遵循同一规则：UseNumber 会递归影响动态容器中的数字。遍历时要分别处理 json.Number、[]any 和 map[string]any，不要用一次类型断言假设所有数字都在顶层。

用边界样例验收类型保留结果

最少准备三类样例：安全范围内的整数、超过安全浮点整数范围的大整数，以及带小数或科学计数法的数字。验收重点不是打印出来“看着一样”，而是确认类型、转换错误和回传字面量都符合接口契约。

func checkNumber(raw json.Number) error {
    if _, err := raw.Int64(); err == nil {
        return nil // 能落入 int64 的值才进入整数业务分支
    }
    if raw.String() == "" {
        return fmt.Errorf("empty JSON number") // 防止自定义输入绕过基本检查
    }
    return fmt.Errorf("unsupported numeric form: %s", raw.String())
}

不要把 Int64() 失败都当作程序异常：小数本来就不该进入整数字段，过大的整数则应交给字符串或高精度类型处理。解析层只负责准确表达输入，业务层再决定是否接受。

常见问题

为什么结构体中的 int64 没有变成 float64？

因为目标字段类型已经确定，解码器会直接尝试写入 int64；float64 是动态接口值的默认数字类型。

UseNumber 能自动保证金额精度吗？

不能。它只保留字面量；金额仍需使用字符串、定点整数或专用 decimal 类型完成精确运算。

可以把 float64 再转成 int64 吗？

不建议。若原始整数已经超过浮点安全范围，转回去可能得到另一个整数。应从解码入口改用结构体或 UseNumber。