在前后端分离的架构中，API接口通常以JSON作为数据交换的载体。Go语言凭借标准库自带的encoding/json包，能够极其方便地在结构体与JSON字符串之间进行转换。但在实际业务场景里，比如分布式系统的雪花算法生成的ID、金融系统中的长订单号等，往往会使用int64类型来存储超大整数。如果直接将这些包含int64大整数的结构体转化为JSON返回给客户端，或者从客户端接收包含大整数的JSON并解析，极易发生精度丢失的问题。这种丢失通常发生在前端JavaScript引擎解析JSON时，因为JavaScript的Number类型无法安全表示超过特定范围的整数。
探究精度丢失的底层根源
要理解为什么Go语言在处理JSON时会出现int64精度丢失，首先需要明确数据在传输和解析过程中的两个关键环节。在Go语言这一端，标准库的encoding/json在将int64类型序列化为JSON时，实际上是将其作为数字类型输出的，也就是在最终的JSON字符串中，它是一串没有引号的数字字符。Go语言本身处理int64没有任何问题，因为它的底层是64位整数，能够精确表示从-2的63次方到2的63次方减1范围内的数值。
问题的核心在于消费端，尤其是浏览器端的JavaScript引擎。JavaScript中的所有数字（无论是整数还是浮点数）在底层统一使用IEEE 754标准的双精度浮点数表示。这意味着JavaScript能够安全表示的最大整数是Number.MAX_SAFE_INTEGER，其值为2的53次方减1，也就是9007199254740991。当Go语言输出的int64值超过了这个安全整数范围，比如一个雪花算法生成的ID为9223372036854775807，JavaScript在解析这个JSON数字时，就会因为存储空间不足而进行近似取整，从而导致最高位的精度丢失。前端拿到的数值已经不再是后端发送的那个准确值了。
策略一使用json.Number进行通用解析
针对从客户端接收JSON并解析到Go结构体时的精度问题，第一种有效的策略是使用json.Number类型。默认情况下，encoding/json在解析JSON数字时，会将其匹配到float64或int64中。如果我们明确知道某些字段可能是超大整数，或者想要全局避免数字精度问题，可以强制让JSON解析器将所有数字先作为字符串保留下来，这就是json.Number的作用。json.Number本质上是一个基于string的类型，它延迟了数字的实际解析过程，直到我们明确调用Int64()或Float64()等方法时才进行转换。
要启用这个机制，我们需要使用json.Decoder并设置UseNumber()选项。这种方式在处理未知结构的JSON数据或者需要高度灵活性的API网关中非常实用。下面是具体的代码实现示例：
package main
import (
"encoding/json"
"fmt"
"strings"
)
func main() {
// 模拟前端传来的包含大整数的JSON数据
jsonData := `{"order_id": 9223372036854775807, "user_name": "test_user"}`
// 使用 Decoder 进行解析
decoder := json.NewDecoder(strings.NewReader(jsonData))
// 设置 UseNumber 选项，让数字解析为 json.Number 而不是 float64
decoder.UseNumber()
// 解析到一个 map 中
var result map[string]interface{}
if err := decoder.Decode(&result); err != nil {
fmt.Println("解析失败:", err)
return
}
// 获取 order_id 字段
orderID := result["order_id"]
// 此时 orderID 的类型是 json.Number
if num, ok := orderID.(json.Number); ok {
// 安全地转换为 int64
val, err := num.Int64()
if err != nil {
fmt.Println("转换为 int64 失败:", err)
return
}
fmt.Printf("成功解析大整数，类型: %T, 值: %d\n", val, val)
}
}使用json.Number的优势在于其通用性极强，只需在解码时设置一次，就能避免整个数据结构中的数字精度丢失。它不需要修改原有的结构体定义，对业务代码的侵入性较小。然而，这种方式的缺点是使用起来相对繁琐。在获取到json.Number之后，我们还需要手动进行类型断言和类型转换，如果JSON结构非常复杂，这种逐层断言和转换的代码会显得臃肿，增加了维护成本。
策略二自定义类型重写序列化接口
另一种更为优雅且对业务层透明的策略，是针对int64定义一个自定义类型，并为该类型实现json.Marshaler和json.Unmarshaler接口。这种策略的核心思想是：在序列化时，将int64的大整数转换为字符串形式输出到JSON中；在反序列化时，将JSON中的字符串形式数字解析回int64。由于JSON字符串在JavaScript中是以字符串类型处理的，因此完全不会触发JavaScript的数字精度限制，前端在展示时可以直接使用这个字符串，或者在需要计算时使用专门的BigInt库。
通过自定义类型，我们可以将精度处理的逻辑封装在类型内部，使得业务逻辑层完全无需关心序列化细节。下面是自定义Int64类型的实现代码：
package main
import (
"encoding/json"
"fmt"
"strconv"
)
// Int64 自定义类型，基于 int64
type Int64 int64
// MarshalJSON 实现 json.Marshaler 接口
// 在序列化时，将 int64 转换为带引号的字符串
func (i Int64) MarshalJSON() ([]byte, error) {
return []byte(fmt.Sprintf("\"%d\"", int64(i))), nil
}
// UnmarshalJSON 实现 json.Unmarshaler 接口
// 在反序列化时，兼容处理字符串形式或数字形式的大整数
func (i *Int64) UnmarshalJSON(data []byte) error {
// 去除可能存在的引号
str := string(data)
if len(str) > 0 && str[0] == '"' {
str = str[1 : len(str)-1]
}
// 将字符串转换为 int64
val, err := strconv.ParseInt(str, 10, 64)
if err != nil {
return err
}
*i = Int64(val)
return nil
}
// Order 订单结构体
type Order struct {
OrderID Int64 `json:"order_id"`
Name string `json:"name"`
}
func main() {
// 模拟从外部接收的 JSON 数据，大整数以字符串形式存在
jsonData := `{"order_id": "9223372036854775807", "name": "test_order"}`
var order Order
if err := json.Unmarshal([]byte(jsonData), &order); err != nil {
fmt.Println("反序列化失败:", err)
return
}
fmt.Printf("反序列化结果: OrderID=%d, Name=%s\n", order.OrderID, order.Name)
// 将结构体重新序列化为 JSON
bytes, err := json.Marshal(order)
if err != nil {
fmt.Println("序列化失败:", err)
return
}
fmt.Println("序列化结果:", string(bytes))
}这种方案的优点非常突出：业务层只需要将结构体中的字段类型从int64替换为我们自定义的Int64类型，其余代码几乎不需要任何修改，序列化和反序列化过程完全自动化。前端获取到的JSON数据中，对应字段的值会带有双引号，例如"order_id":"9223372036854775807"，彻底杜绝了精度丢失。不过它也有一个小小的局限性，那就是前端开发者必须明确知道哪些字段是字符串化的数字，在进行数值计算前需要做类型转换。但考虑到大整数通常用作唯一标识符而非用于算术运算，这种限制在实际业务中通常是可以接受的。