Jackson工具类封装与四层测试设计：从Long精度丢失到高频坑实战

我最早意识到 JSON 工具类必须认真写测试，是在一次订单核对时发现数据库里一条order_id的末尾几位变成了000。那个字段是雪花算法生成的Long，理论上不会重复，也不可能以 0 结尾，结果线上日志里确实就变成了这样。查到最后，问题出在 JSON 序列化这一层——对象转 JSON 再转回对象，精度丢了。从那天起，JacksonUtilTest这个测试类就不只是一个测试文件了，它是整个序列化层最后的兜底防线。这篇博文就围绕 Jackson 工具类的封装、测试设计、精度问题和高频坑展开，给你一份可以直接落地参考的实践经验。

先说清楚本文适合谁：如果你的项目里有人手写ObjectMapper、到处new，或者还在纠结到底用 fastjson 还是 Jackson，又或者你的接口返回给前端后出现过 ID 对不上、日期格式不对、字段多一个就报错之类的问题，那这篇内容基本就是为你准备的。

1. 从一次线上“订单 ID 变了”说起：JSON 精度事故复盘

1.1 事故现场：日志里多出来的三个 0

当时的情况是这样的：A 服务通过消息队列把订单对象发给 B 服务，B 服务收到后落库。某天对账发现，B 库里有一批订单号的最后三位是000，而 A 服务自己的库里订单号是正常的。对比之后发现所有异常订单号都有一个共同点：原始订单号都超过了 JavaScript 的Number.MAX_SAFE_INTEGER（9007199254740991）。

链路里唯一的文本交换格式就是 JSON。A 服务用 Jackson 序列化成字符串，B 服务用 Jackson 反序列化。找个测试类一跑，Long类型字段在 JSON 文本里本身是完整无损的，但反序列化时如果中间经过了前端浏览器、Node 层，或者被某个脚本引擎先做了一次JSON.parse，精度就保不住了。我们那次事故虽然没有经过浏览器，但排查链路让我意识到：JSON 处理过程中的每个转换节点，都有可能在毫无报错的情况下把数字改掉。

1.2 为什么“精度丢失”比“报错”更可怕

如果 Jackson 在遇到超大数字时直接抛异常，那问题反而好解决。真正麻烦的是这种静默改变：序列化成功、反序列化成功、日志不打一个 warning，但数值已经变了。

举个最直观的例子：

Long orderId = 3383281726350452737L; String json = objectMapper.writeValueAsString(orderId); // json = 3383281726350452737，此时还是准的 Object parsed = objectMapper.readValue(json, Object.class); // parsed 是 Long 还是 Integer？看具体 Jackson 版本和值范围 System.out.println(parsed.getClass());

如果你指定了Long作为目标类型，Jackson 能正常转换；但如果你图省事，用Object.class或Map.class接，Jackson 对小整数会默认转Integer，大整数转Long，浮点数转Double。表面看着没毛病，但一旦这个 JSON 字符串在中间被浏览器处理过，所有超过安全范围的数字都会被改写成近似值，而这个改写过程比后端更隐蔽——浏览器里JSON.parse不会有任何提示。

当时我们修复方案很简单：在 A 服务序列化时把Long统一转成字符串输出。这个方案后续还会展开讲，它也是后来JacksonUtilTest里一个永远不敢删的测试用例的来源。

2. 工具选型对比：Jackson 和 fastjson 的根本差异在哪

2.1 热搜问题“Jackson 和 fastjson 哪个好”背后的真实决策逻辑

网上搜“Jackson 和 fastjson 哪个好”，能看到大量对比，大部分集中在 API 简洁程度和性能上。fastjson 的JSON.toJSONString(obj)和JSON.parseObject(text, X.class)确实比 Jackson 写起来省几行，早期压测数据也好看。

但选型不能只看写起来爽不爽，还要考虑三个维度：出问题之后能不能快速修、生态是不是活跃、默认行为是不是安全。

fastjson 前几年出过多个反序列化漏洞，很多安全扫描工具会直接对 fastjson 报高危。虽然官方也一直在修复，但只要你的项目要过安全审计，每次漏洞公告出来就意味着要升级版本、重新验证，这个成本是隐性的。Jackson 社区更活跃，Spring Boot 默认也用它，出了问题搜解决方案基本上能直接找到答案。性能方面，在绝大多数业务场景里，Jackson 和 fastjson 的差距根本到不了需要选型优化的程度，真正的瓶颈通常在网络 IO 和数据库，不在 JSON 解析。

2.2 我在选型时做过的实测与结论

说个我自己做过的粗粒度测试：同样是序列化一个嵌套 5 层、包含 List 和 Map 的业务对象，循环 100 万次，Jackson 和 fastjson 在 JDK 17 下的耗时差异大概在 5% 到 10% 之间。放到真实接口里，这种差异完全被一次日志打印掩盖掉。所以我的结论是：如果你不是在做网关类、超高并发、完全以 JSON 处理为核心中间件的项目，选型优先级应该是安全性大于生态大于性能。这也是为什么后来的工具类封装和测试体系都围绕 Jackson 来搭。

注意：我的意思不是 fastjson 不能用，而是团队在维护、升级、安全扫描上的隐形成本，Jackson 更低。如果你的遗留项目已经在用 fastjson 且稳定运行，也没有必要为了换而换，重点是摸清你当前依赖版本里有没有已知漏洞。

3. JacksonUtil 设计思路：不是把所有 JSON 操作都塞进一个类

3.1 先搞清楚工具类要解决什么问题

写JacksonUtil之前，我先梳理了项目里真实存在的 JSON 操作场景，大致有四类：

1. 把业务对象序列化成 JSON 字符串（写日志、发消息、存缓存）。
2. 把 JSON 字符串反序列化成具体业务对象。
3. 把 JSON 字符串反序列化成List<T>、Map<String, T>这类带泛型的容器。
4. 特殊格式处理：LocalDateTime、Long转字符串、字段命名策略等。

这里面最容易被带偏的是第三类。很多人第一版工具类想写一个public static <T> T parseObject(String json, Class<T> clazz)来通吃，但遇到List<User>时直接用这个方法是行不通的——readValue的第二个参数如果传List.class，拿回来的是一个ArrayList<LinkedHashMap>，强转时不会报错，但后面取字段就开始各种奇怪问题。正确做法是使用TypeReference或先转成JsonNode再treeToValue。

3.2 一个可直接落地的 JacksonUtil 核心代码

我最终落地的工具类里，核心只有几个方法，但每个方法都经过测试用例反复打磨。下面是我觉得比较稳的一版骨架，你可以根据自己项目的包结构调整：

public final class JacksonUtil { private static final ObjectMapper MAPPER = new ObjectMapper() .registerModule(new JavaTimeModule()) .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS) .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) .setSerializationInclusion(JsonInclude.Include.NON_NULL); private JacksonUtil() { } public static String toJson(Object obj) { try { return MAPPER.writeValueAsString(obj); } catch (JsonProcessingException e) { throw new JacksonUtilException("序列化失败: " + obj, e); } } public static <T> T parseObject(String json, Class<T> clazz) { try { return MAPPER.readValue(json, clazz); } catch (JsonProcessingException e) { throw new JacksonUtilException("反序列化失败: " + json, e); } } public static <T> T parseObject(String json, TypeReference<T> typeReference) { try { return MAPPER.readValue(json, typeReference); } catch (JsonProcessingException e) { throw new JacksonUtilException("反序列化失败: " + json, e); } } public static <T> List<T> parseList(String json, Class<T> clazz) { try { JavaType javaType = MAPPER.getTypeFactory() .constructCollectionType(List.class, clazz); return MAPPER.readValue(json, javaType); } catch (JsonProcessingException e) { throw new JacksonUtilException("反序列化 List 失败: " + json, e); } } public static JsonNode parseTree(String json) { try { return MAPPER.readTree(json); } catch (JsonProcessingException e) { throw new JacksonUtilException("解析 JsonNode 失败: " + json, e); } } }

注意这里自定义了一个JacksonUtilException，而不是让方法返回null、也不是把异常吞掉。这一点特别重要。团队里好多同学喜欢在工具类里catch (Exception e) { return null; }，结果线上出了问题从日志里看不到任何蛛丝马迹，只能人工一步一步排查。所以我当初定的规则是：工具类在解析失败时立即抛出运行时异常，并带上原始 JSON 片段，这样日志里直接能看到是哪个字符串出了问题。

3.3 ObjectMapper 单例还是每次新建：这个问题没有争议

很多刚接触 Jackson 的朋友会在每个方法里new ObjectMapper()，担心线程安全。这里可以直接给结论：ObjectMapper 是线程安全的，配置完成后可以安全地作为单例使用。真正不安全的是你在使用过程中又去修改它的配置，比如某个请求里调用了mapper.configure(...)，这会造成全局影响。

Spring Boot 项目里更省事的做法是直接注入容器里的ObjectMapper，或者注入Jackson2ObjectMapperBuilder再自定义配置。但如果你像我们一样在某些非 Spring 环境（比如纯工具包、定时任务脚本）里用，自建一个static final的单例是最稳的。需要不同配置的场景，再单独建ObjectMapper实例，不要共用同一个。

// 不同配置的场景，新建实例，而不是在全局单例上改 ObjectMapper snakeCaseMapper = new ObjectMapper() .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);

4. JacksonUtilTest 用例设计：四个层次，缺一不可

4.1 第一层：序列化反序列化的往返一致性测试

这是最基础、也最容易漏掉的层。很多人觉得User user = new User(...); String json = JacksonUtil.toJson(user); User u2 = JacksonUtil.parseObject(json, User.class); assertEquals(user, u2);就行了，但这里有个隐藏的坑：如果User没重写equals，这个断言永远是false，测试形同虚设。

我后来改成了两段式断言：先断言关键字段值，再用 JSON 层面的语义比较。字段值对比能精确到每一个重要业务字段，JSON 层面对比用JsonNode.equals可以忽略字段顺序：

@Test @DisplayName("用户对象序列化后应能完整反序列化回来") void userObjectRoundTrip() { User user = UserBuilder.buildDefault(); String json = JacksonUtil.toJson(user); User parsed = JacksonUtil.parseObject(json, User.class); assertThat(parsed.getUserId()).isEqualTo(user.getUserId()); assertThat(parsed.getUserName()).isEqualTo(user.getUserName()); assertThat(parsed.getCreatedAt()).isEqualTo(user.getCreatedAt()); JsonNode rawJson = JacksonUtil.parseTree(json); JsonNode parsedJson = JacksonUtil.parseTree(JacksonUtil.toJson(parsed)); assertThat(parsedJson).isEqualTo(rawJson); }

提示：断言为什么用 AssertJ 的assertThat(...).isEqualTo(...)，而不是 JUnit 的assertEquals？因为assertEquals失败时只告诉你 expected 和 actual 不相等，对于长字符串、复杂对象，你根本看不清差异在哪里；AssertJ 会把 diff 打印得非常清楚，这在排查工具类问题时能省大量时间。

4.2 第二层：泛型和容器类型专项测试

我见过太多事故是从一个“看似通用”的泛型方法里冒出来的。List<User>这种最常见的泛型容器，测试用例必须覆盖：

• 空列表：[]应该反序列化成空List，而不是null，更不是报错。
• 单元素列表。
• 列表里某个元素是null：[{"userId":1}, null]这种情况虽然业务上少见，但一旦出现，你的代码不能直接 NPE。
• Map<String, User>的键只能是字符串，这个本身没问题，但 map 里的 value 有没有可能被LinkedHashMap替代？如果你用TypeReference<Map<String, User>>就没问题。

泛型测试有一个实用的技巧：用一个继承TypeReference的匿名内部类来测试嵌套泛型。

@Test @DisplayName("嵌套泛型：List<Map<String, User>> 反序列化") void nestedGenericListMap() { String json = "[{\"u1\": {\"userId\": 1, \"userName\": \"a\"}}, {\"u2\": {\"userId\": 2, \"userName\": \"b\"}}]"; List<Map<String, User>> result = JacksonUtil.parseObject(json, new TypeReference<List<Map<String, User>>>() {}); assertThat(result).hasSize(2); assertThat(result.get(0).get("u1").getUserName()).isEqualTo("a"); }

这个测试如果写成Class<List>那种方式，运行时会直接报ClassCastException或者拿到LinkedHashMap，所以它是检验工具类泛型处理能力的关键用例。

4.3 第三层：边界条件和异常输入的覆盖

抽几个最典型的边界用例：

• null输入：toJson(null)应该返回什么？parseObject(null, X.class)呢？很多工具类在null上行为不一致，有的返回null，有的返回"null"。建议明确：toJson(null)返回"null"，parseObject(null, ...)返回null，并把这两个用例写死在测试里，避免后来的人改代码时把行为改乱。

• 空字符串：parseObject("", X.class)应该怎样？Jackson 默认会报MismatchedInputException，这其实是合理行为，工具类只需保证抛的是统一异常，而不是让调用方去 catch 一大串底层异常。

• 不合法 JSON：parseObject("{userId:1}", User.class)，这种 JSON 里 key 没加双引号的写法在 fastjson 里能解析，但 Jackson 默认拒绝。这类用例必须存在，否则某天有人为了兼容这种脏数据在全局配置里把JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES打开了，反而把接口的健壮性搞坏了。

• 超长字符串字段：比如一个大字段 10MB，Jackson 抗不扛得住。虽然不常用，但如果你的工具类被日志链路使用，这种场景值得加一个。

4.4 第四层：回归保护测试——版本升级和配置调整的防火墙

JacksonUtilTest还有一个隐性的重要作用：版本升级回归。比如 Jackson 从 2.15 升到 2.17，如果行为有变化，你原有的测试会第一时间暴露问题；如果你升了版本但没有跑测试，线上出现诡异行为时你会完全找不到方向。

我自己经历过一次挺典型的回归：Jackson 2.12 版本之前，FAIL_ON_UNKNOWN_PROPERTIES默认是false（忽略未知字段），但从某个版本开始有些模块默认把它调成了true。如果工具类逻辑依赖“忽略未知字段”，升级后接口就全报错了。这时候有一组测试用例在，升级完跑一下就能发现问题，修起来也快。

5. 三个高频坑的完整定位链路与修复实录

5.1 精度问题：从“前端传来算好的结果”到“后端用 BigDecimal 重算”

热搜词里有一条“1-9 高精度减法(subtraction)分数 10 作者 jackson 单位 上海大学计算两数之差输入格”，这让我想到另一个真实高频坑：高精度数字不能只靠前端算，也不能靠 JSON 默认行为来保证精度。

在涉账务系统里，金额计算必须用BigDecimal，但 JSON 序列化BigDecimal有一个常见的坑：如果你把BigDecimal的scale设成了 4 位，比如123.4500，Jackson 默认会原样输出123.4500还是去掉末尾的 0，取决于你是否配置了WRITE_BIGDECIMAL_AS_PLAIN。很多前端parseFloat之后，123.4500直接变成123.45，后面做减法时精度就出现了细微差异。

我当时排查一个对账差异的完整链路大概是这样的：

1. 现象：两边的减法结果差 0.0001。
2. 假设一：数据库 decimal 字段精度不够。查看表结构，是decimal(18, 4)，足够，排除。
3. 假设二：后端BigDecimal.subtract用错了。反复检查了几遍，用的是a.subtract(b)，没有doubleValue介入，排除。
4. 假设三：JSON 反序列化时BigDecimal被转成了Double再转回来。
5. 验证：写一个测试，把BigDecimal对象序列化成 JSON，再反序列化成Object，打印getClass()——结果发现某些场景下确实拿到了Double。
6. 根因：代码里某个中间层使用了Object作为反序列化目标类型，Jackson 把 JSON 数字默认映射为Integer、Long或Double。
7. 修复：把所有“这里只需要转成 Object 看看”的地方，全部改成显式的BigDecimal、Long等具体类型；必须用泛型的场景，统一用TypeReference强制指定。

这类问题根本不需要到生产环境才暴露，一个JacksonUtilTest就能抓住：

@Test @DisplayName("BigDecimal 经过 JSON 往返后精度保持不变") void bigDecimalPrecisionPreserved() { BigDecimal amount = new BigDecimal("12345678901234567890.1234"); String json = JacksonUtil.toJson(amount); BigDecimal parsed = JacksonUtil.parseObject(json, BigDecimal.class); assertThat(parsed).isEqualByComparingTo(amount); }

5.2 LocalDateTime 格式化不一致：同一个接口两种返回格式

另一个高频坑是时间格式。团队里有人接口返回2024-01-01 12:00:00，有人返回2024-01-01T12:00:00，还有人返回数组[2024, 1, 1, 12, 0, 0]。原因基本都是 ObjectMapper 的全局配置不统一：有人只在某个地方配置了JavaTimeModule，另一个服务没配。

在JacksonUtil里，我是这样统一处理的：

ObjectMapper mapper = new ObjectMapper() .registerModule(new JavaTimeModule()) .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

disable(WRITE_DATES_AS_TIMESTAMPS)必须写，否则LocalDateTime序列化成数组，前端拿到后还得自己拼字符串。同时建议给LocalDateTime配一个统一的格式，比如：

JavaTimeModule javaTimeModule = new JavaTimeModule(); javaTimeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))); javaTimeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));

测试里必须覆盖“反序列化一个不在你格式化规则里的时间字符串”的情况，比如前端传2024-01-01T12:00:00，预期是抛异常，而不是静默得到null。这样你就能第一时间知道是前端格式不对，而不是傻傻地在业务代码里排查半天。

5.3 未知字段导致的批量报错：FAIL_ON_UNKNOWN_PROPERTIES 的取舍

以前有个项目对接第三方接口，对方在某个版本加了几个字段，结果我们的接口在没有任何代码改动的情况下大面积报错。日志里的错误指向UnrecognizedFieldException，定位到反序列化配置是FAIL_ON_UNKNOWN_PROPERTIES=true。

这个开关的设置逻辑很简单：如果你直接解析外部不可控的 JSON（第三方回调、消息队列消息），建议关闭这个检测，忽略新的未知字段；如果你是内部服务的严格协议校验，才考虑打开。注意，即使关闭了FAIL_ON_UNKNOWN_PROPERTIES，对于明显格式不对的 JSON（比如字段类型从String变成了数组），Jackson 还是会报错，所以不用担心它会放过所有脏数据。

测试用例方面，我会准备一段带多余字段的 JSON，比如{"userId":1, "userName":"a", "extraField":"x"}，断言反序列化不抛异常，而且extraField被忽略。这个用例一旦写好，以后不管谁动了全局配置，只要跑一遍就能看到结果。

6. 维护阶段：版本升级和团队协作时，JacksonUtilTest 怎么接着用

6.1 升级 Jackson 版本的顺序建议

升级依赖不能直接改pom.xml就完事。我的建议顺序是：

1. 先看当前版本和升级目标版本的release notes，重点关注序列化行为变化、默认配置变化、模块拆分变化。
2. 在本地把依赖版本改掉，跑一遍完整的JacksonUtilTest，看哪些用例挂了。
3. 如果挂了的用例数量很多，优先去判断是行为变化还是配置变化；行为变化要逐个人工核实影响范围，配置变化可能只需在ObjectMapper初始化处加一行配置。

拿 Jackson 2.x 的一个常见升级点为例：早期jsr310模块（jackson-datatype-jsr310）和jackson-module-parameter-names需要单独引入，后续版本把它们统一到某个基础模块里。如果你手动管理 maven 依赖，升级时容易漏掉传递依赖，测试用例会直接暴露NoClassDefFoundError或InvalidDefinitionException，有测试就能早发现。

6.2 防止团队成员“绕过工具类”

有了JacksonUtil，还得防止团队里有人图省事，绕过工具类直接用底层ObjectMapper。这里分享两个实操做法：

• 在代码评审里硬性要求：新增的 JSON 序列化相关代码必须使用JacksonUtil，不能自己new ObjectMapper。
• 在JacksonUtil里加统一的日志切面或者统计埋点，能统计出哪些接口高频使用序列化，万一后续性能优化也有数据支撑。

但是不要强制禁止别人用ObjectMapper。某些场景下确实需要直接操作JsonNode做树模型遍历，用工具类反而绕。重要的是：全局统一的格式、统一的异常、统一的精度策略，必须收敛到工具类这一层，而不是每个开发自己写一套。

6.3 测试命名和场景扩展：往后加用例比“改用例”更重要

JacksonUtilTest运行久了，难免会有一些分支覆盖不到。我的经验是，与其大改结构，不如在原来的四个层次上持续增加场景用例。看到线上出现一个奇怪的 JSON 字符串导致报错，第一反应是把这个字符串脱敏后塞进测试类里作为回归用例，再用@DisplayName标清楚这是哪个业务的什么场景。时间长了，这个测试类就是你的 JSON 处理“字典”，几乎每个线上坑都有对应的用例。

给@DisplayName取名时不要偷懒，比如“测试反序列化”这种用例名毫无价值。更好的写法是“当 JSON 中缺少必填字段时抛出统一异常”“当数字超过 Long 最大值时反序列化为 String”“当 LocalDateTime 格式非法时抛出可读异常消息”。这样别人看报告时不需要打开代码就能知道是哪个行为出了问题。

6.4 关于测试数据：不要只在测试里写“完美”的 JSON

最后分享一个小技巧。很多人的测试 JSON 都是手写的理想化数据，字段齐全、类型正确，这远远不够。我会在测试目录下放几个固定资源文件，比如：

• user_normal.json：正常数据
• user_missing_field.json：缺少一个非必填字段
• user_extra_field.json：多出一个未知字段
• user_empty_string_field.json：某个字符串字段是空字符串
• user_null_field.json：某个字段是null
• user_generic_list.json：泛型列表数据

这些资源文件可以直接被多个测试用例引用，也可以用来模拟第三方接口返回。不要试图在测试代码里构造一个超大字符串去模拟“坏数据”，用资源文件管理，可读性和维护性都高出一大截。

从最开始那个order_id末尾多出三个 0 的事故，到后来把JacksonUtilTest扩展成覆盖协议、精度、时间、异常、回归等多维度的测试集，我最大的体会是：JSON 处理这类底层工具，开发时看起来只需要几行代码，但它被全局调用，任何一个隐蔽的行为变化都可能被放大成生产事故。把线上遇到过的每一个怪问题沉淀成测试用例，比多写十个业务接口都更有价值。如果你现在还没有专门针对 Jackson 工具类的测试集，建议从这篇文章里挑几个核心用例，先跑通再谈演进。