项目概述

Snack JSONPath 是一个高性能 Java JSONPath 处理框架，支持：

• JSON DOM 文档模型
• JSONPath 查询（兼容 jayway.jsonpath 和 IETF JSONPath RFC 9535）
• JSONSchema 生成与校验（支持 Draft-07 / Draft-2019-09 / Draft-2020-12）

语言: Java (JDK 8+)

构建: Maven 多模块项目

模块结构

snackjson/
├── snack4/                    # 核心 JSON 库
├── snack4-jsonpath/           # JSONPath 实现模块
├── snack4-jsonschema/         # JSONSchema 模块
├── snack4-test/               # 测试模块
└── snack4-test17/            # Java 17+ 专用测试

核心模块详解

1. snack4（核心库）

主要类

目录结构

snack4/src/main/java/org/noear/snack4/
├── ONode.java              # 入口类
├── DataType.java           # 数据类型
├── Feature.java            # 配置特性
├── Options.java            # 配置选项
├── annotation/              # 注解（自定义序列化）
├── codec/                  # 编解码系统
│   ├── CodecLib.java       # 编解码注册表
│   ├── BeanEncoder.java    # Bean 编码器
│   ├── BeanDecoder.java    # Bean 解码器
│   ├── decode/             # 解码器实现
│   ├── encode/             # 编码器实现
│   └── create/             # 对象创建实现
├── json/                   # JSON 解析/写入
└── jsonpath/               # JSONPath 集成

2. snack4-jsonpath（JSONPath 实现）

目录结构

snack4-jsonpath/
├── JsonPath.java              # 主查询引擎
├── JsonPathParser.java        # 路径表达式解析器
├── JsonPathProviderImpl.java   # SPI 实现
├── JsonPathException.java    # 异常类
├── QueryResult.java           # 查询结果
├── QueryContext.java          # 查询上下文接口
├── QueryContextImpl.java     # 查询上下文实现
├── QueryMode.java           # 查询模式枚举
├── FunctionLib.java         # 函数库（可扩展）
├── Function.java            # 函数接口
├── FunctionHolder.java      # 函数持有器
├── OperatorLib.java         # 操作符库（可扩展）
├── Operator.java            # 操作符接口
├── selector/               # 节点选择器
│   ├── Selector.java       # 选择器接口
│   ├── NameSelector.java  # 按名称
│   ├── IndexSelector.java # 按索引
│   ├── WildcardSelector.java  # 通配符
│   ├── SliceSelector.java # 切片 [0:3]
│   ├── FilterSelector.java # 过滤器
│   └── QuerySelector.java # 查询选择
├── segment/               # 路径段
│   ├── Segment.java       # 段接口
│   ├── AbstractSegment.java # 抽象基类
│   ├── SelectSegment.java # 基本选择
│   ├── DescendantSegment.java # 递归后代 ..
│   └── FuncSegment.java   # 函数段
├── filter/               # 过滤器表达式
│   ├── Expression.java    # 表达式（RPN 算法）
│   ├── Term.java         # 词项
│   ├── Operand.java     # 操作数
│   └── Token.java        # 词法标记
├── operator/             # 比较操作符
│   ├── Operator.java     # 操作符接口
│   ├── CompareOperator.java # 比较运算
│   ├── MatchesOperator.java # 正则匹配
│   ├── InOperator.java   # in
│   ├── NinOperator.java  # nin
│   ├── ContainsOperator.java # 包含
│   ├── StartsWithOperator.java # 开头匹配
│   ├── EndsWithOperator.java  # 结尾匹配
│   ├── EmptyOperator.java  # 空检查
│   ├── SizeOperator.java  # 大小检查
│   └── ...
├── function/             # 内置函数
│   ├── LengthFunction.java  # length / size
│   ├── CountFunction.java   # count
│   ├── MinFunction.java    # min
│   ├── MaxFunction.java    # max
│   ├── AvgFunction.java    # avg
│   ├── SumFunction.java    # sum
│   ├── StddevFunction.java # stddev
│   ├── FirstFunction.java  # first
│   ├── LastFunction.java   # last
│   ├── KeysFunction.java   # keys
│   ├── MatchFunction.java  # match (RFC)
│   ├── SearchFunction.java # search (RFC)
│   └── ...
└── util/                  # 工具类
    ├── TokenizeUtil.java  # 词法分析
    ├── IndexUtil.java     # 索引计算
    ├── RangeUtil.java     # 范围计算
    ├── RegexUtil.java     # 正则匹配
    └── ...

路径段 (Segment)

选择器 (Selector)

内置函数

内置操作符

查询模式

3. snack4-jsonschema（JSONSchema）

snack4-jsonschema/
├── JsonSchema.java              # 主类
├── JsonSchemaException.java     # 异常类
├── SchemaVersion.java           # 版本枚举（DRAFT_7/2019-09/2020-12）
├── SchemaKeyword.java          # 关键字常量接口
├── SchemaType.java             # 类型枚举
├── SchemaFormat.java           # 格式常量
├── generate/                   # Schema 生成
│   ├── JsonSchemaGenerator.java  # 生成器
│   ├── MapperLib.java            # 映射注册表
│   ├── SchemaMapper.java         # 架构映射接口
│   ├── SchemaPatternMapper.java   # 模式映射接口
│   ├── TypeMapper.java           # 类型映射接口
│   └── TypePatternMapper.java    # 类型模式映射接口
└── validate/                   # Schema 校验
    ├── JsonSchemaValidator.java  # 校验器
    ├── PathTracker.java         # 路径跟踪器
    ├── CompiledRule.java        # 编译后规则
    └── impl/                    # 校验规则实现
        ├── TypeRule.java              # 类型规则
        ├── RequiredRule.java          # 必填规则
        ├── EnumRule.java             # 枚举规则
        ├── StringConstraintRule.java  # 字符串约束
        ├── NumericConstraintRule.java # 数值约束
        ├── ArrayConstraintRule.java   # 数组约束
        ├── AdditionalPropertiesRule.java
        └── PropertyNamesRule.java

校验规则实现

架构图

┌─────────────────────────────────────────────────────────────┐
│                         ONode                               │
│                    (统一入口类)                              │
└────────────────────────┬────────────────────────────────────┘
                         │
    ┌────────────────────┼────────────────────┐
    │                    │                    │
    ▼                    ▼                    ▼
┌────────────┐   ┌──────────────┐   ┌─────────────────┐
│ JsonReader │   │ JsonWriter   │   │ JsonPathProvider │
│  (解析)    │   │  (序列化)    │   │     (SPI)       │
└────────────┘   └──────────────┘   └────────┬─────────┘
                                             │
                    ┌─────────────────────────┼─────────────────────────┐
                    │                         │                         │
                    ▼                         ▼                         ▼
           ┌────────────────┐        ┌────────────────┐        ┌────────────────┐
           │ JsonPathParser │        │    JsonPath    │        │  FunctionLib   │
           │   (词法解析)   │        │   (查询引擎)   │        │   (内置函数)   │
           │                │        │                │        │                │
           │ TokenizeUtil   │        │ QueryContext   │        │ min/max/avg    │
           │ ↓               │        │ QueryResult    │        │ length/count   │
           │ List<Token>    │        │ QueryMode      │        │ match/search   │
           │ ↓               │        │                │        │ ...            │
           │ RPN 转换       │        │ select()       │        └────────────────┘
           └───────┬────────┘        │ create()       │
                   │                  │ delete()        │
                   ▼                  └────────┬─────────┘
           ┌────────────────┐                 │
           │  Expression    │                 │
           │ (过滤器表达式) │                 │
           │                │                 │
           │ RPN 算法求值   │◀────────────────┤
           │    ↑           │                 │
           │ OperatorLib    │                 │
           └───────┬────────┘                 │
                   │                          │
                   ▼                          ▼
    ┌─────────────────────────────┬──────────────────────────────┐
    │         Segment             │          Selector           │
    │       (路径段)              │        (节点选择器)          │
    │                             │                            │
    │ SelectSegment ──────────► │ NameSelector ──── 属性名   │
    │ DescendantSegment ──────► │ IndexSelector ─── 数组索引 │
    │ FuncSegment ────────────► │ WildcardSelector ── 通配符 │
    │                             │ SliceSelector ───── 切片   │
    │                             │ FilterSelector ──── 过滤   │
    │                             │ QuerySelector ───── 查询   │
    └─────────────────────────────┴──────────────────────────────┘

核心数据结构

DataType 枚举

enum DataType {
    Undefined,  // 未初始化
    Null,       // null 值
    Boolean,    // true/false
    Number,     // Integer, Long, Double, BigDecimal
    String,     // 字符串
    Date,       // java.util.Date
    Array,      // List<ONode>
    Object      // Map<String, ONode>
}

JSONPath 查询执行流程

1. 解析阶段: JsonPath.parse(path)
   ├── 词法分析: TokenizeUtil.tokenize()
   │   └── 字符串 → List<Token>
   │
   ├── 语法解析: JsonPathParser.parse()
   │   └── List<Token> → List<Segment>
   │
   └── 缓存: ConcurrentHashMap 存储已解析路径

2. 执行阶段: JsonPath.select(root)
   │
   ├── QueryContextImpl 初始化
   │   └── 设置 QueryMode.SELECT
   │
   ├── 遍历 Segments:
   │   └── for each Segment:
   │       ├── SelectSegment.resolve(ctx, currentNodes)
   │       │   └── 调用 Selector 选择节点
   │       ├── DescendantSegment.resolve()
   │       │   └── 递归遍历所有后代
   │       └── FuncSegment.resolve()
   │           └── 调用 FunctionLib 执行函数
   │
   └── Selector 选择:
       ├── NameSelector → 按属性名匹配
       ├── IndexSelector → 按数组索引
       ├── WildcardSelector → [*] 通配
       ├── SliceSelector → [1:3] 切片
       ├── FilterSelector → [?()] 过滤
       │   └── Expression.test() 使用 RPN 求值
       │       └── OperatorLib 调用操作符
       └── QuerySelector → 嵌套查询

3. 结果阶段
   └── QueryResult 包装节点列表
       ├── getNodeList() → List<ONode>
       ├── asNode() → 第一个节点
       └── asString/asInt/asDouble → 类型转换

关键算法

JSONSchema 校验执行流程

1. 编译阶段: JsonSchemaValidator 初始化
   └── Schema 解析 → Map<Path, CompiledRule>
   └── 规则预编译：类型、约束、条件（allOf 合并）

2. 校验阶段: validator.validate(data)
   └── PathTracker 跟踪当前路径
   └── 按路径匹配 CompiledRule 执行校验
   └── 递归处理 properties / items
   └── 处理条件 anyOf / oneOf

3. 异常阶段
   └── 校验失败 → 抛出 JsonSchemaException
   └── 包含路径和错误信息

Schema 生成流程

1. 入口: schema.generate(Type)
   └── JsonSchemaGenerator 构造

2. 生成阶段: doGenerate()
   └── 循环引用检测（visited 缓存）
   └── 根据类型分发处理：
       ├── Bean → 生成 properties/required
       ├── Array → 生成 items
       ├── Collection → 生成 items（支持泛型）
       └── Map → 生成 additionalProperties

3. 定义处理（可选）
   └── enableDefinitions=true 时生成 $defs/definitions
   └── 支持循环引用 $ref

公开 API

ONode 主入口

// 创建
ONode.ofJson(String json)           // 解析 JSON 字符串
ONode.ofBean(Object bean)           // 转换 Java Bean
ONode.ofJson(Reader reader)         // 从流解析

// DOM 操作
oNode.set("key", value)             // 设置属性
oNode.add(value)                    // 添加数组元素
oNode.get("key")                    // 获取子节点
oNode.get(0)                       // 获取数组元素

// JSONPath 查询
oNode.select("$.store.book[0]")     // 查询节点
oNode.exists("$.store.book")         // 检查存在
oNode.create("$.new.path")          // 创建路径
oNode.delete("$.old.path")           // 删除节点

// 序列化
oNode.toJson()                      // 转 JSON 字符串
oNode.toBean(Class<T>)              // 转 Java Bean
oNode.toBean(TypeRef<T>)            // 带泛型转换

JsonPath 直接访问

// 解析路径（支持缓存）
JsonPath path = JsonPath.parse("$.store.book[*].author");

// 查询
ONode result = path.select(rootNode);           // 在 ONode 上查询
ONode result = JsonPath.select(json, "$.path"); // 静态查询
ONode result = JsonPath.select(rootNode, "$.path");

// 检查存在
boolean exists = JsonPath.exists(rootNode, "$.store");

// 创建路径（不存在时创建）
ONode created = JsonPath.create(rootNode, "$.new.path");

// 删除节点
boolean deleted = JsonPath.delete(rootNode, "$.old.path");

// 查询结果处理
QueryResult qr = path.select(rootNode);
qr.getNodeList();     // 获取所有匹配节点
qr.asNode();          // 获取第一个匹配节点
qr.asString();        // 作为字符串
qr.asInt();           // 作为整数
qr.asDouble();        // 作为浮点数

路径语法示例

过滤器表达式

// 基本比较
[?(@.age == 18)]
[?(@.name != "test")]
[?(@.price > 100)]

// 正则匹配
[?(@.email =~ /^.*@.*\.com$/)]

// 集合操作
[?(@.status in ["active","pending"])]
[?(@.role nin ["admin"])]

// 字符串操作
[?(@.name contains "john")]
[?(@.url startsWith "https")]
[?(@.ext endsWith ".json")]

// 逻辑组合
[?(@.age > 18 && @.active == true)]
[?(@.vip == true ** @.balance > 1000)]

// 嵌套路径
[?(@.address.city == "Beijing")]
[?(@..price > 100)]  // 递归搜索

JSONSchema

// 创建 Schema 实例（支持 Builder 模式）
JsonSchema schema = JsonSchema.builder()
    .version(SchemaVersion.DRAFT_7)          // 草案版本
    .enableDefinitions(true)                  // 启用定义规范
    .printVersion(true)                      // 打印 $schema
    .build();

// 添加自定义映射
schema.addSchemaMapper(User.class, new CustomSchemaMapper());
schema.addTypeMapper(new CustomTypePatternMapper());

// 生成 Schema
ONode schemaNode = schema.generate(User.class);
String schemaJson = schemaNode.toJson();

// 校验数据
JsonSchemaValidator validator = schema.createValidator(User.class);
validator.validate(dataNode);  // 抛出 JsonSchemaException 则校验失败

// 也可直接用 JSON 字符串创建校验器
JsonSchemaValidator validator2 = JsonSchema.builder()
    .createValidator("{\"type\":\"object\"}");

核心功能

SchemaKeyword 关键字

配置

Options 配置选项

// 创建配置实例
Options opts = Options.of(
    Feature.Write_PrettyFormat,      // 漂亮格式输出
    Feature.Write_UseSmlSnakeStyle   // 字段名下划线风格
);

// 或者链式配置
Options opts = new Options(false)
    .dateFormat("yyyy-MM-dd")       // 日期格式
    .writeIndent("  ")              // 缩进
    .addFeatures(Feature.Write_PrettyFormat)
    .addEncoder(MyClass.class, new MyEncoder())
    .mapFactory(LinkedHashMap::new)
    .listFactory(ArrayList::new);

常用特性 (Feature)

依赖关系

snack4-parent (父 POM)
├── snack4 (核心)
│   └── 依赖: eggg, slf4j-api
├── snack4-jsonpath
│   └── 依赖: snack4
├── snack4-jsonschema
│   └── 依赖: snack4, slf4j-api