根本原因是Go json.Unmarshal将JSON数字默认解析为float64导致超53位精度丢失;解决方案是前后端统一以字符串传输大整数,后端用,string标签或json.Number,前端禁止数字字面量传ID。

Gin 接口返回大整数(如雪花 ID、微秒时间戳)时出现精度丢失,根本原因不是 Gin 本身的问题,而是 Go json.Unmarshal 默认把 JSON 数字解析为 float64,一旦原始数字超过 2^53 - 1(即 9007199254740991),精度就不可逆丢失——哪怕你结构体字段声明的是 int64 也救不回来。
后端返回时必须把大整数转成字符串
这是最直接、最可靠、前后端成本最低的方案。前端 JavaScript 天然无法安全表示超 53 位整数,所以后端不该传数字,而应传字符串。
- Spring Boot(Jackson)用
@JsonFormat(shape = JsonFormat.Shape.STRING)或@JsonSerialize(using = ToStringSerializer.class)注解单个字段 - Go Gin 中,对结构体字段加
,string标签即可让json.Marshal自动转字符串:ID string `json:"id,string"` - 若用
map[string]interface{}动态构造响应,手动调fmt.Sprintf("%d", id)或strconv.FormatInt(id, 10)转字符串再塞进去 - 切忌在返回前做
int64 → float64 → string这类中间转换,会先丢精度再转串,白忙活
Gin 中接收前端大整数时要用 json.Number
如果前端已按约定传了 {"id": "12345678901234567890"}(带引号),那 Go 层可以用 json.Number 安全接收;但如果前端误传了 {"id": 12345678901234567890}(无引号),这个数字在 JS 环境里早就被 JSON.stringify 弄丢了精度,Go 收到的就是错值,没法补救。
- 结构体字段声明为
ID json.Number `json:"id"`,后续调ID.Int64()检查溢出,或ID.String()直接取原文本 - 别对
json.Number做算术运算,它不是数值类型;要算必须先转,且必须检查 error - 若不能改结构体(比如处理第三方回调或泛型 map),需在绑定前接管
ctx.Request.Body,用json.NewDecoder(r.Body).UseNumber()替换默认行为 -
ctx.BindJSON()绕不开float64解析,绝对不要依赖它处理可能超限的字段
前端必须配合传字符串,否则 Go 层一切努力都白搭
很多团队只改后端,却没同步推动前端改调用方式,结果问题依旧。关键点在于:JSON 规范里 12345678901234567890 和 "12345678901234567890" 是两种完全不同的 token,前者进 JS 就挂,后者才能保真。
- 前端发请求时,确保对象字段是字符串:
{ id: String(userId) }或显式写死引号:{"id": "12345678901234567890"} - Axios 请求前可用
transformRequest拦截,对已知大整数字段自动 toString - 避免用
JSON.stringify({ id: 12345678901234567890 })直接序列化——此时 JS 已经把它转成float64了 - 如果前端用 TypeScript,建议把 ID 类型定义为
string而非number,从类型层杜绝误用
最容易被忽略的一点:精度丢失是链路问题,不是单点修复能解决的。后端用 json.Number 或 ,string 标签只是半程,前端是否严格按字符串传输、是否在 JS 内部做无意识的 Number(id) 转换,都会让前面所有努力失效。真正的闭环,得前后端一起守住“ID 永远是字符串”这条线。


















