JSON 处理这块，Java 生态里从来都不缺工具。光是序列化库就能列出一长串，更别提各种格式化、对比工具。但很多时候我们会遇到一个尴尬的情况：单个库用起来都挺顺手，一旦需要组合完成一件事，比如既要序列化又要可视化对比，就会在几个库之间来回切，API 风格还不统一，代码写得很别扭。
这次要聊的 TOON 实战，就是把 JToon 和 json-io 组合起来用的一套方案。JToon 负责把 JSON 以结构化的方式呈现出来，json-io 负责底层的对象序列化和反序列化。两者配合，基本可以覆盖从对象转 JSON、JSON 转对象、JSON 格式化、结构对比到字段差异分析的完整链路。
如果你正在维护一个遗留系统，里面充满了各种嵌套对象、循环引用、甚至带泛型的复杂集合，又不想为了调试和测试反复写一堆自定义的 JSON 处理代码，这篇内容应该能给你一些可以直接抄作业的思路。
1. 为什么用 json-io 而不是 Jackson
很多人一上来就问我，为什么不用 Jackson 或者 Gson，非要用 json-io 这个听起来没那么大众的库。我理解这个疑问，毕竟 Jackson 生态成熟，文档多，遇到问题随便一搜就是答案。但 json-io 有一个特性是 Jackson 默认做不到的：它可以在序列化时保留对象图的结构信息，处理循环引用非常自然。
举个实际场景。假设你有一个Customer对象，里面关联了Order列表，而每个Order又回指向Customer。用 Jackson 默认配置去序列化这种结构，直接栈溢出。你需要手动加@JsonIgnore或者写自定义 serializer，但这样一来，反序列化回来的时候关联关系就断了。
json-io 的做法不一样。它序列化时会写入类型元数据，对循环引用的处理是内置的。它通过记录对象路径的方式来引用已经序列化过的对象，而不是无限递归展开。这意味着你可以直接用JsonWriter.objectToJson(customer)把整个对象图完整输出，然后通过JsonReader.jsonToJava(json)把它还原成一个所有关联关系都还在的对象。调试和测试的时候，这种能力能帮你省掉大量处理循环引用的模板代码。
当然，json-io 并不是要取代 Jackson。如果你的项目是一个标准的 REST API 服务，需要对接前端，需要定制字段命名策略，那 Jackson 依然是更合适的选择。json-io 的定位更偏向于内部工具、测试夹具、数据迁移、缓存存储这些场景。它不强制你为每个类设计 DTO，也不需要你为了 JSON 输出调整领域模型。用一句话总结：Jackson 是面向 API 的，json-io 是面向对象图的。
2. 环境准备与首次上手
2.1 引入依赖
json-io 的坐标比较简单，直接在pom.xml里加上：
<dependency> <groupId>com.cedarsoftware</groupId> <artifactId>json-io</artifactId> <version>4.14.0</version> </dependency>TOON 这边，它通常是指那个用于 JSON 可视化和对比的库，可以和 json-io 配合使用。引入方式类似：
<dependency> <groupId>com.cedarsoftware</groupId> <artifactId>toon</artifactId> <version>2.22.0</version> </dependency>TOON 本身依赖了 json-io，所以如果你只引入 toon 也不会有问题。但我习惯两个都显式声明，因为代码里会直接引用 json-io 的JsonWriter和JsonReader，图个明确。
2.2 第一个对象图序列化案例
创建一个测试用的领域模型：
public class Customer { private String name; private int age; private List<Order> orders; // 构造方法、getter/setter 省略 } public class Order { private String orderNo; private double amount; private Customer customer; // 构造方法、getter/setter 省略 }构建一个带循环引用的对象图：
Customer c = new Customer("张三", 30); Order o = new Order("A001", 199.9, c); c.setOrders(List.of(o)); String json = JsonWriter.objectToJson(c); System.out.println(json);输出的 JSON 不会因为Order.customer -> Customer -> orders -> Order这种循环而爆炸。内部会用一个类似路径引用的机制标记已序列化的对象，反序列化的时候能自动还原引用关系。看到这里，你应该能理解为什么我前面说 json-io 对对象图友好——这是它最核心的差异化能力。
再反序列化回来：
Customer c2 = JsonReader.jsonToJava(json); System.out.println(c2.getOrders().get(0).getCustomer() == c2);这一行输出true，说明反序列化之后的对象图保持完整，不是副本堆叠，而是真正的引用关系还原。这在构建测试数据的时候非常香。
2.3 TOON 的初始化与基础用法
TOON 本身提供一个可视化的表格/树形展示界面，主要用来展示对象图和 JSON 结构。它的核心入口通常是：
Toon toon = new Toon(); toon.show(customer);调用之后会弹出一个窗口，左边是对象树，右边是属性明细，支持搜索、排序。如果你在写一个内部管理工具的调试面板，或者做数据对比分析，用这个能省掉不少前端工作量。需要注意的是，TOON 需要运行在图形界面环境下，如果你在无头服务器上用，它也能工作，但展示窗口就看不到了，这时候主要用的是它的对比和 JSON 输出能力。
我第一次用 TOON 的时候踩了个小坑：它的默认显示语言是通过区域设置自动判断的，如果你的系统区域是中文，界面也会切成中文，这是预期的行为。但如果你在英文环境下跑，希望界面显示中文，需要设置user.language=zh，这个在实际部署时可以作为系统参数传入。
3. json-io 序列化的核心配置与细节
3.1 序列化选项：MetaKey 那些事
json-io 序列化时会在 JSON 里写入一些以@开头（默认前缀）的元数据键名，用来标记类型信息。比如：
{ "@type": "Customer", "name": "张三", "orders": { "@type": "java.util.List", "@items": [ { "@type": "Order", "orderNo": "A001" } ] } }这就是 json-io 的能力来源。这些元数据让反序列化时能准确还原具体类型，而不是盲转成Map和List。但有时候你不需要这些元数据，比如只是临时把对象转成 JSON 做日志输出，那就可以关掉：
JsonWriter.JsonWriterBuilder builder = JsonWriter.builder(); builder.setPrettyPrint(true); builder.setWriteTypeMetaData(false); JsonWriter writer = builder.build(); String compactJson = writer.write(customer);关闭类型元数据之后，输出的 JSON 更干净，但代价是反序列化时无法精确还原类型，只会得到 Map。所以我的建议是：序列化后还需要还原的场景必须保留元数据，纯展示/传输场景可以关掉。这个开关很关键，实际项目里我们就是因为在日志系统里默认关闭了元数据，结果排查问题的时候没法直接把日志拷出来还原对象，后来又改回开启状态。
3.2 自定义映射：类名太长怎么办
默认情况下，json-io 会把类的全限定名写在@type里。如果你序列化了一堆领域对象，JSON 体积会明显变大，而且观感不好。json-io 提供了类名映射机制，可以把长类名映射成短别名：
MetaFactory.addMetaFactory(Customer.class, "Customer", null); MetaFactory.addMetaFactory(Order.class, "Order", null);之后序列化时，@type就是"Customer"而不是"com.xxx.model.Customer"。反过来反序列化时，看到Customer也能正确映射回类。这种配置适合在一个固定的领域模型集合内使用，如果你的系统有多个模块，类名可能冲突，那就要小心，建议加上不同的前缀，比如"crm:Customer"和"trade:Customer"。
3.3 序列化时的字段过滤和日期格式
json-io 也支持自定义 writer。如果你不希望某个字段被序列化，可以这样：
JsonWriter.JsonWriterBuilder builder = JsonWriter.builder(); builder.addWriter(String.class, (writer, out, target) -> { Date d = (Date) target; out.writeString(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(d)); });日期类型格式化的时候，默认是输出时间戳还是 ISO 格式？我记不太清了，但实测下来，自己指定一个 writer 最稳妥，避免不同环境解析出不同结果。一个比较实用的配置是统一把java.util.Date输出成yyyy-MM-dd HH:mm:ss，这样调试时一眼能看懂时间。你可以把 Date、LocalDate、LocalDateTime 都加一个自定义 writer。
3.4 反序列化的安全边界
反序列化这块有件事必须提醒：json-io 的设计目标是完整还原对象图，它允许 JSON 里的类型信息直接指定任意类并触发构造。如果数据来源不可信，这会有安全风险。官方提供了允许列表机制：
MetaFactory.setAllowedClasses(Set.of( Customer.class, Order.class, String.class ));设置了允许列表之后，JSON 里如果出现了列表之外的类名，反序列化会直接失败。在解析外部输入时，这个限制建议一定要加上，别嫌麻烦。你可以在测试环境先不加，看完整的行为，生产环境再收紧。
4. 用 TOON 做 JSON 查看与对比
4.1 核心功能：从树形视图到字段级对比
TOON 的窗口打开后，你会看到左侧是一个树，展示整个对象图的层级结构。点击某个节点，右侧显示该节点的类名、属性名、值、类型。它跟普通的 JSON 查看器最大的区别是：TOON 直接操作的是 Java 对象，而不是解析 JSON 字符串。换句话说，TOON 依赖的是序列化器给出的对象图，而 json-io 恰好是那个能输出完整对象图的序列化器。
这种组合最适合的场景是：你有一个复杂的领域模型，程序运行到某个阶段时，你想看看对象内部到底变成了什么样。直接断点调试也行，但在生产环境或者处理大批量数据时，TOON 的窗口会更直观。
4.2 对比两个对象：TOON 的差异分析
TOON 还支持一次性加载两个对象，然后以并排的形式展示差异。比如你有两个版本的配置对象，想确认属性级别哪里变了：
Config oldConfig = loadFromDb(); Config newConfig = loadFromFile(); Toon.showDifferences("Old Config", oldConfig, "New Config", newConfig);它会逐个字段做对比，差异的字段用高亮标出来。如果某个字段是对象，它会递归往下展开，直到叶子节点。这种字段级对比在定位数据不一致问题的时候非常好用。我有一次排查线上配置项不生效的问题，就是通过这种对比发现新配置文件的某个枚举值拼写跟旧版不一致，那是肉眼扫根本看不出来的差别。
4.3 在无界面环境下的替代用法
如果你在 CI 环境或者无头服务器上运行测试，TOON 的窗口显然用不了。这时候可以直接用 json-io 把对象转成 JSON，然后做字符串层面或者结构层面的断言。更精细一点，可以先把对象转成 JSON，再反序列化成Map，然后用递归遍历的方式做字段级 diff。TOON 内部其实也是这么做的，只是它把 diff 结果可视化出来了。
我之前在一个数据迁移项目里就是这么干的：批量读取迁移前后的对象，转成 JSON 之后做字段级对齐，所有嵌套字段如果一致就跳过，不一致就记录字段路径和前后值。这样生成的 diff 报告比对着表数据人工核对快得多。
5. 常见问题与排查技巧实录
5.1 实战中遇到的高频问题速查表
| 现象 | 原因 | 解决方案 |
|---|---|---|
反序列化时抛ClassNotFoundException | JSON 里的@type指向了当前 ClassLoader 无法加载的类 | 检查类型名是否正确，检查依赖是否完整，必要时配置类名映射 |
| 序列化后 JSON 巨大 | 对象图包含大量共享引用，json-io 默认会写入完整引用路径 | 关闭一部分字段的序列化，或者只序列化需要的子图 |
| 反序列化后字段缺失 | 字段不是 public，也没有 getter/setter，json-io 无法访问 | 增加 getter/setter，或配置字段级自定义处理器 |
| 反序列化得到的对象类型不对 | JSON 中没有类型元数据 | 序列化时开启setWriteTypeMetaData(true) |
| 循环引用导致 StackOverflow | 没有启用 json-io 的循环检测，或手动关闭了 | 确认没有关闭内置的循环引用处理，检查是否有自定义 writer 递归调用 |
| TOON 窗口打不开 | 当前线程不是 EDT 线程，或运行在无图形界面环境 | 改用SwingUtilities.invokeLater或在非 UI 环境下改用 json-io 输出 |
5.2 排查技巧一：先让对象“开口说话”
遇到复杂的对象图问题，我的第一反应不是去翻源码，而是先把对象转成 JSON 看一遍。很多时候问题就藏在 JSON 的结构里。用 json-io 转出来的 JSON 会带类型信息，如果你发现某个对象的类型变成了LinkedHashMap，说明序列化时类型信息丢了，或者反序列化时没有拿到类型元数据。
这种场景我建议先把@type元数据打开看一眼，确认类型描述正确，再决定是保留元数据还是用自定义映射。元数据是理解运行时对象结构的线索，不要一上来就关掉。
5.3 排查技巧二：用 JDK 自带的可视化工具辅助
如果你处理的不是普通 Java 对象，而是一个需要序列化后跨系统传递的数据流，那可以先用JsonWriter.objectToJson成 JSON，再交给 TOON 展示。这样即使对象图本身很复杂，你也能从树形界面上看出引用关系是不是正常。遇到字段重复或者引用路径过长的时候，一眼能看到。
当然，如果对象太复杂，你也可以考虑只展示部分关键字段。json-io 允许对字段做过滤，TOON 展示时也可以右键某个节点选择“仅显示该子树”。两种方式结合，在大型对象上排查的效率会高很多。
5.4 避坑：类型元数据与 Jackson 的兼容性
json-io 的@type元数据格式跟 Jackson 的@class是完全不一样的设计。如果你在同一个系统里同时使用 json-io 和 Jackson，要注意这两个库产出的 JSON 不要混着反序列化。比如 json-io 序列化的 JSON 交给 Jackson 去读，Jackson 会把这些@type当成普通字段处理，结果就是得到一个 Map。反过来也一样，json-io 读到 Jackson 的 TypeReference 信息也无法正确识别。
我的习惯是：在代码里明确区分两种 JSON 的用途。对外 API 统一用 Jackson，对内缓存、测试、工具开发统一用 json-io。避免混用是减少这类问题的第一步。如果你确实需要跨库转换，需要写一层转换层，自己把 json-io 的格式映射成 Jackson 能识别的结构，但这个工作量一般不值得。
5.5 避坑：不要贪图“一行代码解决所有序列化问题”
有的开发者用 json-io 顺手之后，会把所有对象的序列化都交给它，包括对外接口。我见过一个项目，把所有 REST 响应都改成 json-io 输出，结果前端同事叫苦不迭，因为 json-io 的默认字段顺序、空值处理策略跟 Jackson 不一样。这种迁移属于典型的工具选型不合适。
json-io 适合放在系统内部，作为对象图的 JSON 表达工具。如果要做对外输出，还是建议用更通用的 Jackson，并配合 DTO 设计。工具选型这件事，不能只看单点能力强，要看它在整个系统里的定位是否合适。
最后再分享一个细节
用 json-io 的时候，我习惯在项目里统一封装一个 ObjectGraphUtil，把序列化、反序列化、对比这些操作都包一层。这样后续如果基础库升级，改动的成本会小很多，也不至于在业务代码里散落一堆 JsonWriter 的调用。
这个工具类的核心就几个方法：toJsonById、fromJsonById、diffAsString、prettyPrint。每个方法内部都做默认配置，尽量让调用方少传参。比如 toJsonById 默认开启 prettyPrint 和类型元数据，因为这种用法主要就是给调试和测试用的，可读性优先。
还有一个比较推荐的实践是：把 json-io 和 TOON 的功能组合在一起写一个小注解，标注在需要调试的字段上，运行时自动展示对象图。这算是一种调试期增强的玩法，不影响生产代码，但在排查问题的时候能省不少时间。这些做法不一定适合所有项目，但如果你正在为复杂对象图的维护烦心，拿这套组合拳去试试，应该会有收获。
