1. 项目概述当ID从后端“旅行”到前端时它“变胖”了最近在做一个用户中心模块后端用的是经典的雪花算法生成分布式ID数据库里存的是BIGINTJava实体类里用的是Long。一切都运行得很完美直到前端同事跑过来问我“哥你这个用户ID怎么在页面上显示出来是1234567890123456700最后两位怎么变成00了我明明传的是1234567890123456789啊。”这场景是不是很熟悉如果你也遇到过从后端返回的Long类型ID特别是超过2^53-1的大整数到前端JavaScript环境后最后几位数字“失真”的问题那么恭喜你你正踩在前后端数据交互一个非常经典的“精度丢失”的坑里。这绝不是代码写错了而是JavaScript和Java这两个语言在数字处理上的根本差异导致的。简单来说Java的Long是64位带符号整数能精确表示的范围非常大-2^63 到 2^63-1。而JavaScript中所有数字都以IEEE 754标准的64位双精度浮点数即Number类型存储。对于整数它能安全、精确表示的范围是-2^53 1到2^53 - 1即-9007199254740991到9007199254740991。一旦雪花算法生成的ID超过这个范围大约17位十进制数在JSON序列化/反序列化过程中精度丢失就必然会发生。这个问题在分布式系统、高并发业务中尤为突出因为雪花算法生成的ID就是为了突破单机自增ID的瓶颈其值很容易超过JavaScript的安全整数范围。它导致的不仅仅是显示错误更严重的是可能导致后续业务逻辑出错比如用这个“失真”的ID去调用详情接口结果返回“数据不存在”。2. 问题根源深度剖析不是Bug是“特性”要彻底解决这个问题我们必须先理解其背后的原理而不是简单地寻找一个“补丁”。知其然更要知其所以然。2.1 雪花算法ID的特性雪花算法Snowflake生成的ID是一个64位的长整型其典型结构是1位符号位通常为041位时间戳毫秒级可用约69年10位工作机器ID5位数据中心ID 5位机器ID支持1024个节点12位序列号每毫秒可生成4096个ID这样一个ID用十进制表示长度通常是18位或19位。例如135792468013579246818位987654321098765432119位。它们远远超出了JavaScript的Number.MAX_SAFE_INTEGER即9007199254740991只有16位。2.2 JavaScript的Number类型与精度丢失JavaScript没有真正的整数类型。当它接收到一个来自JSON的、超出安全整数范围的数字时会尝试用双精度浮点数来近似表示它。浮点数的表示方式决定了它无法精确表示所有的大整数。我们可以用一个简单的例子来演示// 在浏览器控制台或Node.js中尝试 const bigId 1357924680135792468; console.log(bigId); // 输出1357924680135792400 console.log(bigId 1357924680135792468); // 输出false你会发现ID的最后几位被“四舍五入”或直接置零了。这是因为在二进制浮点数表示中没有足够的位数来精确表达这个十进制数的所有信息。2.3 数据传输链路上的关键环节精度丢失发生在数据从后端Java对象到前端JavaScript对象的转换链路上后端序列化Spring Boot等框架使用Jackson或Fastjson等库将Long类型的ID转换为JSON数字。注意此时数字本身是精确的问题不在后端。网络传输JSON以文本形式传输例如{id: 1357924680135792468}。文本本身是精确的。前端反序列化前端使用JSON.parse()或axios、fetch等库自动解析响应时将JSON文本中的数字1357924680135792468转换为JavaScript的Number类型。就是这一步发生了精度丢失。所以问题的症结在于我们默认使用了不适合大整数的数据类型JavaScriptNumber来承载需要精确传输的数据。3. 解决方案全景图从“打补丁”到“治本”解决思路的核心在于避免让大整数以JSON数字的形式进行传输。一旦它成了JSON中的纯数字前端就无力回天了。因此我们必须在其被序列化为JSON之前就将其转换为一种能够无损传递的格式。以下是几种常见的解决方案我将从简单到复杂从“临时补救”到“根本解决”逐一分析。3.1 方案一后端序列化时转为字符串最常用、最推荐这是目前最主流、最彻底的解决方案。思路很简单既然JavaScript的Number类型会丢失精度那我们就不传数字传字符串。字符串在JSON序列化和反序列化过程中是不会有任何变化的。实现方式1全局配置Jackson如果你使用的是Spring Boot默认的Jackson可以在application.yml中配置spring: jackson: generator: write-numbers-as-strings: true但这个配置会将所有数字都写成字符串包括普通的整数、小数可能会影响其他接口不够精细。实现方式2注解配置精准控制更推荐在具体的ID字段上使用JsonFormat注解import com.fasterxml.jackson.annotation.JsonFormat; public class UserDTO { JsonFormat(shape JsonFormat.Shape.STRING) private Long id; private String username; // ... getters and setters }这样这个id字段在序列化成JSON时就会变成id: 1357924680135792468。前端接收到的是一个字符串需要参与运算时比如比较大小再用BigInt转换或者直接作为字符串参数传给后端。实现方式3自定义序列化器对于老项目或需要更复杂控制的情况可以自定义一个JsonSerializerimport com.fasterxml.jackson.core.JsonGenerator; import com.fasterxml.jackson.databind.JsonSerializer; import com.fasterxml.jackson.databind.SerializerProvider; import java.io.IOException; public class LongToStringSerializer extends JsonSerializerLong { Override public void serialize(Long value, JsonGenerator gen, SerializerProvider serializers) throws IOException { // 将Long值直接写成字符串 gen.writeString(value.toString()); } }然后在实体类字段上使用JsonSerialize注解JsonSerialize(using LongToStringSerializer.class) private Long id;实操心得全局配置改动小但影响广可能会破坏已有前端逻辑如果前端依赖了数字类型。我强烈推荐使用JsonFormat(shape JsonFormat.Shape.STRING)注解的方式精准、明确、无副作用。这是团队协作中最清晰的约定。3.2 方案二自定义Jackson的ObjectMapper如果你希望所有Long类型都自动转为字符串但又不想影响其他Integer、Double等类型可以自定义一个ObjectMapperBean。Configuration public class JacksonConfig { Bean public ObjectMapper objectMapper() { ObjectMapper objectMapper new ObjectMapper(); SimpleModule module new SimpleModule(); // 为Long类型添加自定义序列化器 module.addSerializer(Long.class, new JsonSerializerLong() { Override public void serialize(Long value, JsonGenerator gen, SerializerProvider serializers) throws IOException { // 判断数值范围只有可能超出安全范围的才转字符串 // 这里简单处理所有Long都转String也可加上判断条件 if (value 9007199254740991L || value -9007199254740991L) { gen.writeString(value.toString()); } else { gen.writeNumber(value); } } }); // 为long基本类型也添加可选 module.addSerializer(Long.TYPE, new JsonSerializerLong() { Override public void serialize(Long value, JsonGenerator gen, SerializerProvider serializers) throws IOException { gen.writeNumber(value); } }); objectMapper.registerModule(module); return objectMapper; } }这种方式更加灵活可以加入逻辑判断只对可能出问题的“大Long”进行转换。但复杂度较高需要仔细测试。3.3 方案三前端使用BigInt进行处理辅助方案ES2020引入了BigInt类型专门用于表示任意精度的整数。前端在接收到大整数字符串后可以将其转换为BigInt进行运算。// 假设后端返回 {“id”: “1357924680135792468”} const response await axios.get(/api/user/1); const idString response.data.id; const idBigInt BigInt(idString); // 转换为BigInt console.log(idBigInt); // 1357924680135792468n (注意后面的n) // 可以进行大整数运算 const anotherBigInt idBigInt 1n; // 正确但是请注意BigInt不能和普通的Number混合运算。许多第三方库如lodash、API如JSON.stringify对BigInt直接处理会报错对BigInt的支持还不完善。它解决了前端计算的精度问题但没有解决传输问题。如果后端依然传数字在JSON.parse时精度已经丢失了你再转BigInt也无力回天。因此此方案必须与方案一后端传字符串结合使用。3.4 方案四使用自定义类型或DTO包装在一些严谨的架构中会为ID定义专门的类型而不是直接用Long。// 定义值对象 public class UserId { private final Long value; public UserId(Long value) { this.value value; } public Long getValue() { return value; } // 重写toString序列化时自动调用 Override public String toString() { return value.toString(); } } // 在DTO中使用 public class UserDTO { private UserId id; // 而不是 Long id private String username; }然后为UserId类配置序列化器使其总是输出字符串。这种方式将领域概念显式化更符合DDD领域驱动设计思想但会引入一定的复杂度。4. 实战配置与避坑指南理论说完了我们来点实际的。假设你是一个Spring Boot项目的负责人决定采用方案一注解方式来解决这个问题。以下是完整的操作步骤和你会遇到的坑。4.1 后端改造步骤识别实体与DTO首先找出所有包含雪花算法ID或其他可能的大Long的实体类、DTO、VO。常见的如User、Order、Product等的主键id字段以及作为外键的userId、orderId等。添加注解在每一个需要前端精确接收的Long类型字段上添加JsonFormat(shape JsonFormat.Shape.STRING)。// UserDTO.java public class UserDTO { JsonFormat(shape JsonFormat.Shape.STRING) private Long id; private String name; JsonFormat(shape JsonFormat.Shape.STRING) // 创建人ID也可能很大 private Long createdBy; // ... 其他字段 }测试接口启动你的应用调用相关API。使用Postman或浏览器查看响应确认ID字段是否已经变成了带双引号的字符串。正确响应{id: 1234567890123456789, name: 张三}错误响应{id: 1234567890123456800, name: 张三}最后几位变了4.2 前端适配调整后端改完前端不动的话页面可能会挂掉。因为之前拿到的是number现在拿到的是string。查找所有使用ID的地方全局搜索用到ID的JavaScript/TypeScript代码。常见场景显示document.getElementById(userId).innerText user.id;(这个一般没问题字符串也能显示)比较if (selectedId currentUser.id) {...}(这里可能出问题selectedId可能是数字currentUser.id现在是字符串全等比较会为false)作为参数传递axios.get(/api/orders/${orderId})(如果orderId是字符串模板字符串处理没问题)参与数学运算let newId oldId 1;(如果oldId是字符串会变成字符串拼接123 1 1231逻辑错误)统一处理策略策略A推荐全程字符串。在前端将所有接收到的ID都视为字符串处理。比较时使用而非或者显式转换// 比较 if (String(selectedId) String(currentUser.id)) { ... } // 作为URL参数 axios.get(/api/orders/${orderId}) // orderId 已经是字符串直接使用策略B关键处转换。在需要计算或与历史数字ID比较的地方使用BigInt或Number转换但要注意Number转换大数会丢失精度。// 如果确定ID在安全范围内可以转Number const numId Number(response.data.id); // 如果ID可能很大使用BigInt const bigId BigInt(response.data.id); // 但BigInt不能直接用于DOM显示或作为普通API参数通常需要再转回字符串 const param bigId.toString();策略C前端请求时指定反序列化。有些HTTP客户端库如axios可以配置响应转换器但通常不建议因为治标不治本。4.3 数据库与MyBatis的考量有同学会问ID转成字符串了那MyBatis的#{}占位符还能用吗数据库查询会受影响吗完全不会。JsonFormat注解只影响Jackson将Java对象转为JSON输出的这个环节。它并不改变你Java对象中id字段本身的Long类型。在你的Service、Mapper层里id依然是一个Long类型的值和数据库交互没有任何变化。// Service层 public UserDTO getUserById(Long id) { // 传入的id是Long User user userMapper.selectById(id); // 传给MyBatis的是Long return convertToDTO(user); // 在转换DTO时注解生效输出JSON时id变字符串 }所以后端内部逻辑完全无需改动。5. 常见问题与排查实录在实际落地过程中我遇到了不少坑这里分享出来希望能帮你节省时间。问题1加了JsonFormat注解但ID在JSON里还是数字排查首先检查你的Controller返回的是不是这个DTO对象。其次检查是否有其他全局配置或自定义的ObjectMapper覆盖了注解行为。最粗暴的调试方法在字段的getter方法上打上断点看看序列化时是否经过这里。或者检查依赖中是否有多个Jackson版本冲突。解决确保注解加在了最终返回给前端的DTO/VO字段上而不是内部的Entity上。Entity通常用于数据库映射DTO用于网络传输。问题2前端部分页面正常部分页面ID还是精度丢失排查这大概率是“历史数据”和“新接口”混用导致的。有些老接口没有改造依然返回数字类型的ID新接口返回了字符串。前端代码如果没有统一处理就会表现不一致。解决必须制定统一的团队规范并逐步或一次性改造所有相关接口。可以借助代码扫描工具找出所有返回包含Longid的接口进行批量注解添加。问题3序列化成了字符串但反序列化前端传ID给后端时报错场景前端提交一个JSON{id: 123, name: xxx}后端用RequestBody UserDTO接收结果报错“无法将String转换为Long”。原因JsonFormat默认只指定了序列化Java对象-JSON的行为。你需要用shape JsonFormat.Shape.STRING它同时指明了序列化和反序列化时都按字符串处理。或者你可以配合使用JsonFormat和JsonProperty的access属性进行更精细的控制。解决确保注解配置完整。如果希望该字段只读不接收前端传入可以设置JsonFormat(shape JsonFormat.Shape.STRING)并在反序列化时忽略它或者使用JsonProperty(access JsonProperty.Access.READ_ONLY)。问题4使用Swagger/OpenAPI文档生成的模型显示ID类型是string还是integer影响如果后端显示是string但前端同学根据之前integer的类型定义来写代码可能会产生困惑。解决Springfox或Springdoc OpenAPI通常会根据Jackson的注解来生成类型。添加了JsonFormat(shape JsonFormat.Shape.STRING)后Swagger模型应该会正确显示为string。记得在改动后刷新或重新生成前端API类型定义文件如TypeScript的.d.ts文件。问题5对性能有影响吗分析将数字转为字符串传输理论上会增加一点点网络带宽因为字符比数字的字节表示通常更长。但在实际业务中这种增长微乎其微一个18位ID数字传输可能占8字节字符串占18字节2字节引号。相比于精度丢失导致的业务错误和排查成本这点开销完全可以接受。JSON本身也是文本协议。最后我个人在实际项目中的体会是“后端序列化为字符串”是最优解。它从根源上切断了精度丢失的可能性方案简单、明确对前后端改造范围可控。在团队内定好规范后可以将这个处理方式作为基础开发规范之一在新项目中从一开始就避免这个问题。对于老项目可以作为一个技术债制定计划逐步修复。记住在分布式系统和微服务架构下数据的精确性远比那一点点传输效率重要得多。