Go JSON 怎样把超大整数先保留为文本再做业务校验

处理 JSON 里的订单号、外部流水号或雪花 ID 时，最稳妥的做法不是一上来把它解码成 float64，而是先保留数字字面量，再按业务允许的范围转换。固定字段可以用 json.RawMessage 延迟解析；动态对象可以让 Decoder.UseNumber 把数字放进 json.Number。最后调用 String() 或 Int64() 做明确的格式和范围判断。

如果一个 JSON 整数可能超过 Go 的 int64，先保存它的文本形式，再决定是拒绝、转成 int64，还是交给 math/big.Int。不要用 float64 作为业务编号的中间格式。

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

先用 RawMessage 留住数字原文

json.RawMessage 适合处理“字段知道在哪里，但暂时不决定它是什么类型”的情况。它保存一段原始 JSON 值，可以把解析动作推迟到业务层；因此，像 9007199254740993 这样的整数字面量不会先经过 float64。

package main

import (
    "encoding/json"
    "fmt"
)

type Envelope struct {
    ID      json.RawMessage `json:"id"`
    Payload json.RawMessage `json:"payload"`
}

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

    var envelope Envelope
    if err := json.Unmarshal(data, &envelope); err != nil {
        panic(err)
    }

    // RawMessage 先保留字节，业务层还可以区分数字、字符串和 null。
    fmt.Println(string(envelope.ID))
    fmt.Println(string(envelope.Payload))
}

这个结构的重点不是把字段变成字符串，而是暂缓决定。若上游把编号写成 JSON 字符串，ID 的原文会带引号；若上游传数字，原文就是数字字面量。后续校验可以据此拒绝类型不符合约定的输入。

动态字段用 UseNumber 得到 json.Number

当 JSON 结构是动态的，例如一个 map[string]any 里有很多业务字段，json.Unmarshal 默认会把 JSON 数字放成 float64。这时可以先创建 Decoder，调用 UseNumber，让数字进入接口值时保持为 json.Number。

package main

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

func main() {
    input := `{"order_id":9007199254740993,"retry":2}`
    decoder := json.NewDecoder(strings.NewReader(input))

    // UseNumber 避免动态数字在解码阶段先落成 float64。
    decoder.UseNumber()

    var object map[string]any
    if err := decoder.Decode(&object); err != nil {
        panic(err)
    }

    // Number 保留数字字面量，可在业务边界按需转换。
    number, ok := object["order_id"].(json.Number)
    if !ok {
        panic("order_id 不是 JSON 数字")
    }
    fmt.Println(number.String())
}

UseNumber 只改变动态数字的落点，不等于自动完成范围校验。拿到 json.Number 后仍然要明确：这个字段只接受整数，还是也允许小数；它能否放进 int64；超出范围时是否保留为文本或改用大整数。

先看 String，再决定是否是整数

json.Number.String() 返回数字的字面量文本。对只接受整数的字段，可以先检查文本中是否有小数点或指数，再调用 Int64。这个顺序能把“格式不对”和“范围不够”分成两类错误。

package main

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

var errNotInteger = errors.New("不是整数数字")

func parseInt64Number(value json.Number) (int64, error) {
    text := value.String()
    // 整数字段不接受小数和科学计数法，先按字面量拒绝。
    if strings.ContainsAny(text, ".eE") {
        return 0, errNotInteger
    }

    // Int64 负责把合法整数转换到 int64，并报告越界错误。
    parsed, err := value.Int64()
    if err != nil {
        return 0, fmt.Errorf("整数超出 int64 范围: %w", err)
    }
    return parsed, nil
}

func main() {
    number := json.Number("9007199254740993")
    parsed, err := parseInt64Number(number)
    fmt.Println(parsed, err)
}

这里没有把字符串简单地转成 int64。String 负责观察输入形态，Int64 负责转换和范围边界。对于 1.0、1e3 这类值，即使数学上可能等于整数，也应先按接口约定决定是否允许，而不是悄悄放宽规则。

超出 int64 时保留文本或使用 big.Int

如果编号确实可能超过 int64，不要为了得到一个普通整数而截断或转成浮点数。最简单的选择是保存 json.Number.String() 的结果作为业务文本；如果需要比较、加减或做范围运算，可以用 math/big.Int 解析十进制整数。

package main

import (
    "encoding/json"
    "fmt"
    "math/big"
)

func parseLargeInteger(value json.Number) (*big.Int, error) {
    result := new(big.Int)
    // SetString 的 base 10 只接受十进制整数，失败时不返回可用结果。
    if _, ok := result.SetString(value.String(), 10); !ok {
        return nil, fmt.Errorf("不是可解析的十进制整数: %q", value.String())
    }
    return result, nil
}

func main() {
    number := json.Number("9223372036854775808")
    value, err := parseLargeInteger(number)
    if err != nil {
        panic(err)
    }

    // 大整数保留精确值，适合比较或继续做大整数运算。
    fmt.Println(value.String())
}

这段代码只处理已经确定为 JSON 数字的 json.Number。如果字段来自 RawMessage，应先确认它不是带引号的字符串、不是 null，再把原文交给 json.Number 或大整数解析器。

把三层判断组合成业务字段解析

固定字段可以把原始值先放进结构体，再由一个函数统一完成类型、格式和范围判断。下面的示例只接受 JSON 数字，不接受带引号的编号；在 int64 范围内返回整数，超出范围则返回精确文本。

package main

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

type Order struct {
    ID json.RawMessage `json:"id"`
}

type ParsedID struct {
    Int64 *int64
    Text  string
}

func parseOrderID(raw json.RawMessage) (ParsedID, error) {
    literal := strings.TrimSpace(string(raw))
    // 引号、空值和空输入不属于本接口约定的 JSON 数字。
    if literal == "" || literal == "null" || strings.HasPrefix(literal, "\"") {
        return ParsedID{}, fmt.Errorf("id 必须是 JSON 数字")
    }
    if strings.ContainsAny(literal, ".eE") {
        return ParsedID{}, fmt.Errorf("id 必须是十进制整数")
    }

    number := json.Number(literal)
    if parsed, err := number.Int64(); err == nil {
        // 范围内的值保留为 int64，方便后续查询或比较。
        return ParsedID{Int64: &parsed}, nil
    }

    // 越过 int64 后用 big.Int 确认它仍是精确整数文本。
    large := new(big.Int)
    if _, ok := large.SetString(literal, 10); !ok {
        return ParsedID{}, fmt.Errorf("id 不是有效整数: %q", literal)
    }
    return ParsedID{Text: large.String()}, nil
}

func main() {
    var order Order
    if err := json.Unmarshal([]byte(`{"id":9223372036854775808}`), &order); err != nil {
        panic(err)
    }
    parsed, err := parseOrderID(order.ID)
    if err != nil {
        panic(err)
    }
    fmt.Println(parsed.Text)
}

实际项目里可以根据数据库字段、下游 API 和接口协议，选择只保留文本，或把 ParsedID 拆成带状态的领域类型。重要的是转换点只有一个：JSON 解码层保存原文，业务层作出范围决策，后续代码不再猜测这个编号是否已经被浮点数改写。

常见问题

为什么不直接把 JSON 字段定义成 string？

如果协议明确要求上游传 JSON 字符串，定义成 string 很合适；但标题中的场景是上游传 JSON 数字。直接定义成 string 会把数字和字符串两种协议混在一起，RawMessage 更适合先识别原始类型。

UseNumber 会自动支持任意大的整数吗？

不会。它只是让动态数字以 json.Number 形式保留字面量。是否能放进 int64、是否改成文本或使用 big.Int，仍由业务代码决定。

可以直接对 Number 调用 Float64 吗？

只有在字段本来就是浮点数并且可以接受浮点语义时才这样做。订单号、外部流水号等需要精确比较的整数，不应先经过 Float64。

RawMessage 保存的是字符串吗？

它保存的是原始 JSON 编码值。JSON 字符串会包含引号，JSON 数字则保留数字文本；因此仍然需要先判断 JSON 类型，再进入对应的业务解析。

可以把这套规则记成一句话：固定字段先用 RawMessage 留住原文，动态字段用 UseNumber 得到 json.Number，然后用 String 判断格式、用 Int64 判断范围，超出范围就保留文本或交给 big.Int。