SJF4J 五分钟入门：Java 的实用 JSON 门面

Java 中的 JSON 处理很少是简单的。

在实际应用中，数据不断在以下形式之间流转：

• POJO（普通Java对象）
• Map / List
• JSON 字符串
• 配置文件
• 模式不断演进的 API

Java 开发者常常被迫做出痛苦的选择：

要么要类型安全，要么要灵活性——二者不可兼得。

SJF4J（Java 简单 JSON 门面） 就是为了消除这种取舍而构建的。

SJF4J 是什么？

SJF4J 是流行 JSON 库（Jackson、Gson、Fastjson2）及相关格式（YAML、Properties）之上的一个轻量级门面。它提供一个用于结构化数据处理的统一语义层，完全基于 JSON 规范。它不替代你的 JSON 解析器，而是在它们之上统一你的结构化数据处理方式。

核心理念：基于对象的节点树

SJF4J 没有引入自定义的 JSON AST（抽象语法树），而是将现有的 Java 对象视为 JSON 节点。这被称为基于对象的节点树[Object-Based Node Tree (OBNT)]。

在 OBNT 中：

• JSON 对象 → JsonObject、Map、POJO
• JSON 数组 → JsonArray、List、数组
• JSON 值 → Java 原生类型

一切都保持为普通的 Java 对象，只是在上层附加了 JSON 语义。

快速示例

JsonObject jo = JsonObject.fromJson("""
{
  "id": 1,
  "active": true
}
""");

int id = jo.getInt("id");              // 类型安全
String active = jo.asString("active"); // Boolean → String 转换

SJF4J 提供三种访问级别：

• getNode → 原始访问
• getXxx → 类型安全访问
• asXxx → 语义访问，支持跨类型转换

你可以为每次调用选择严格程度。

基于路径的访问（符合 RFC 规范）

SJF4J 完全支持：

• JSON 路径（RFC 9535）
• JSON 指针（RFC 6901）

String name = jo.asByPath("$.user.name");
List<Integer> ids = jo.findByPath("$.items[*].id", Integer.class);

同样的路径 API 适用于：

• JSON
• Map / List
• POJO
• 混合对象图

动态 + 类型化：JOJO

SJF4J 引入了 JOJO（JSON 对象 Java 对象）—— 一个扩展了 JsonObject 的领域对象。

class User extends JsonObject {
    String name;
}
user.getName();               // 类型化访问
user.getString("age");        // 动态访问
user.findByPath("$..name");   // JSON 语义访问

你可以从动态访问开始，逐步添加结构 —— 而无需破坏 API。

使用 JsonPatch 进行声明式转换

SJF4J 支持：

• JSON 补丁（RFC 6902）
• JSON 合并补丁（RFC 7386）

JsonPatch patch = JsonPatch.diff(source, target);
patch.apply(source);

补丁操作在 POJO、Map、List 和 JSON 对象上统一工作。

SJF4J 何时大放异彩？

如果你符合以下情况，SJF4J 是理想选择：

• 处理不断演进或半结构化的数据
• 既需要灵活性又需要类型安全
• 希望在多个 JSON 库上使用统一的 API
• 关注 JSON 规范

总结

SJF4J 让面向 JSON 的 Java 开发成为可能 —— 无需过早锁定方案或编写过多样板代码。

它小巧、可组合，并且由规范驱动。

👉 GitHub: https://github.com/sjf4j-projects/sjf4j

---

【注】本文译自：SJF4J in 5 Minutes: A Practical JSON Facade for Java