fastjson2 JSONPath 取不存在路径,为什么会抛 “not support”?

fastjson2 JSONPath 取不存在路径,为什么会抛 "not support : r"?

一次流式取值引发的"读串位"问题排查记录

环境:JDK 8、com.alibaba:fastjson:2.0.55(兼容包装层)、com.alibaba.fastjson2:fastjson2:2.0.39

日期:2026-10-26


0. TL;DR

  • JSON 本身是合法的,路径语法也没问题,问题在于路径中间某个字段不存在。
  • JSONPath.extract(String, String) 和 JSONPath.eval(String, String) 走的是 JSONReader 流式求值:一段一段地"边走边找"。
  • fastjson 会按路径形状把 JSONPath 编译成不同的子类 (JSONPathSingleName / JSONPathTwoSegment / JSONPathMulti 等),多路径和类型化还有更多专用实现。这些是性能优化,但不同实现在"路径缺失"时的语义并不完全等价;选型建议见第 6 节。
  • 当某个字段找不到时,schema 为 name 的段并不会告诉后续段"已经失配了";它会把 reader 停在父对象之后 的位置,后续的 [index] 段仍会在这个位置继续解析,于是把下一个兄弟字段的 key 当成了数组元素来读。
  • 结果是:错误信息里出现的字符与路径毫无关系,可能是 e、r,也可能是 }......取决于 reader 漂移后落到的位置;如果父对象后面正好没有内容,则会"安静地"返回 null------不报错不代表安全。
  • 修复方式:改用 JSONPath.eval(Object, String)(先解析成对象再求值),或者先取父级路径并判空,再取子路径。

1. 问题现象

1.1 入参与代码

订单报文(字段齐全,唯独没有 couponDetail):

json 复制代码
{
  "payload": {
    "orderNo": "SO202610260001",
    "buyerId": "U10086",
    "amount": 199.0,
    "couponList": [
      { "couponId": "C-1", "discount": 10 },
      { "couponId": "C-2", "discount": 20 }
    ]
  },
  "traceId": "tr-9f3c"
}

代码:

java 复制代码
Object couponId = JSONPath.extract(json, "$.payload.couponDetail[0].couponId");

预期:couponDetail 不存在,返回 null。

实际:直接抛异常。

1.2 实际异常

复制代码
Exception in thread "main" com.alibaba.fastjson2.JSONException:
not support : r, offset 158, character r, line 1, column 159,
fastjson-version 2.0.39 {"payload":{"orderNo":"SO202610260001",...},"traceId":"tr-9f3c"}
    at com.alibaba.fastjson2.JSONPathSegmentIndex.accept(JSONPathSegmentIndex.java:536)
    at com.alibaba.fastjson2.JSONPathMulti.extract(JSONPathMulti.java:357)
    at com.alibaba.fastjson2.JSONPath.extract(JSONPath.java:56)
    at com.alibaba.fastjson2.JSONPath.eval(JSONPath.java:66)

1.3 第一轮排除

先排除几个常见怀疑:

怀疑点 结论
JSON 格式错误 ❌ 不是,报文可以正常解析
路径语法错误 ❌ 不是,$.payload.couponDetail[0].couponId 完全合法
couponDetail 拼写问题 ❌ 拼写没问题,是报文里确实没有这个字段
偶发的解析器问题 ❌ 不是偶发,同一报文 + 同一路径稳定复现

但有一个细节很可疑:报错字符是 r,不是路径里的任何字符 。r 来自报文字段 traceId 的第二个字符。这说明 reader 已经跑到了与目标路径无关的位置。


2. 最小复现:换一组数据看规律

为了确认触发条件,我构造了 5 组报文,统一使用路径:

复制代码
$.payload.couponDetail[0].couponId

2.1 五组样例

A:payload 后面还有兄弟字段 traceId(触发异常)

json 复制代码
{"payload":{"orderNo":"SO202610260001","buyerId":"U10086","amount":199.0,"couponList":[{"couponId":"C-1","discount":10},{"couponId":"C-2","discount":20}]},"traceId":"tr-9f3c"}

B:payload 是最后一个字段(同样缺失,但不报错)

json 复制代码
{"payload":{"orderNo":"SO202610260001","buyerId":"U10086","amount":199.0,"couponList":[{"couponId":"C-1","discount":10}]}}

C:路径完整存在(对照组)

json 复制代码
{"payload":{"couponDetail":[{"couponId":"C-9","discount":5}]},"traceId":"tr-9f3c"}

D:兄弟字段名很短(报另一种错)

json 复制代码
{"payload":{"orderNo":"SO202610260001"},"v":1}

E:兄弟字段是对象(报错字符又变了)

json 复制代码
{"payload":{"orderNo":"SO202610260001"},"remark":{"text":"none"}}

2.2 结果矩阵

编号 结构特征 extract(String, path) 结果
A payload 后跟 traceId ❌ JSONException: not support : r, offset 158
B payload 是最后一个字段 ✅ 返回 null(不报错)
C couponDetail 存在 ✅ 返回 "C-9"
D payload 后跟 "v":1 ❌ JSONException: invalid escape character EOI
E payload 后跟 "remark":{...} ❌ JSONException: not support : e

2.3 从矩阵里读出三件事

  1. 是否报错,取决于 reader 漂移后落到的字符:通常与缺失字段所在对象后面还有没有兄弟字段、以及还剩几层闭合括号有关;与路径本身、与 JSON 是否合法都无关。
  2. 报错字符和异常类型也不固定 :A 是 r,E 是 e,D 是另一种错误。因为 reader 漂移后碰到的 token 不同,解析器只能"遇到什么报什么"。
  3. B 返回 null 只是碰巧 :reader 正好走到了输入末尾,没有东西可解析。它不代表 couponDetail 存在,也不代表这个写法安全。

3. 根因:流式 JSONPath 的分段执行

3.1 两条不同的求值路线

fastjson2 的 JSONPath 有两类入口:

API 求值方式
JSONPath.extract(String json, String path) 用 JSONReader 流式求值,边走边解析
JSONPath.eval(String json, String path) 内部同样转成 extract(JSONReader),本质一样
JSONPath.eval(Object root, String path) 基于已解析的对象求值,不做流式 reader 解析

出问题的是前两条。包装层 com.alibaba.fastjson.JSONPath 的 extract(String, String) / eval(String, String) 最终也都委托到 fastjson2 的流式实现,所以表现一致。

调用链:

复制代码
JSONPath.eval(String, String)
  └─ JSONPathMulti.extract(JSONReader)
       └─ JSONPathSegmentIndex.accept(JSONReader, Context)   ← 在这里抛异常

3.2 路径被拆成多个段

$.payload.couponDetail[0].couponId 会被拆成 4 段:

序号 段 类型
1 payload 字段名段
2 couponDetail 字段名段
3 [0] 数组下标段
4 couponId 字段名段

JSONPathMulti.extract(JSONReader) 的做法是:所有段共用同一个 JSONReader,前一段解析到哪里,后一段就从哪里继续。

关键代码(fastjson2 2.0.39,JSONPathMulti.java:344-366):

java 复制代码
for (int i = 0; i < size; i++) {
    JSONPathSegment segment = segments.get(i);
    JSONPathSegment nextSegment = ...;

    context = new Context(this, context, segment, nextSegment, 0);
    if (eval) {
        segment.eval(context);
    } else {
        segment.accept(jsonReader, context);
    }

    if (context.eval) {
        eval = true;
        if (context.value == null) {
            break;      // 只有"成功求值且结果为 null"才停止
        }
    }
}

注意:如果某一段"没找到字段",context.eval 仍然是 false,循环不会停止,后面的段会继续在这个已经跑偏的 reader 上执行。

3.3 逐段追踪样例 A

报文尾部:

复制代码
... "couponList":[...]}, "traceId":"tr-9f3c"}
                       ^
                       payload 的结束大括号
步骤 发生了什么 执行后 jsonReader.ch
1 payload 段命中,下一段是字段名,reader 停在 payload 的 { 上 {
2 couponDetail 段在 payload 内找不到;扫到 payload 的 },nextIfObjectEnd() 吃掉 } 和后面的逗号 "(traceId 的起始引号)
3 JSONPathSegmentName 第 535 行又调用了一次 next() t(traceId 的首字符;下一步 [0] 会再前进到 r)
4 [0] 段 JSONPathSegmentIndex.accept 无条件 next(),然后把它当成数组元素解析 r → 命中 default 分支,抛出 not support : r

对应的源码:

  • JSONPathSegmentName.java:534-536:

    java 复制代码
    if (jsonReader.nextIfObjectEnd()) {
        jsonReader.next();   // !!多走了一步
        break;
    }
  • JSONReaderUTF16.java:1018-1065 的 nextIfObjectEnd():遇到 } 时,不只是吃掉 },还会顺便吃掉后面的逗号 ,并把 ch 定位到下一个 token 的开头。

  • JSONPathSegmentIndex.java:437-547:

    java 复制代码
    // ... 省略类型判断
    jsonReader.next();                     // 无条件前进,JDK 8 文本解析
    _for:
    for (int i = 0; jsonReader.ch != EOI; ++i) {
        if (jsonReader.ch == ']') { ... }
    
        boolean match = index == -1 || index == i;
        if (!match) { jsonReader.skipValue(); ...; continue; }
    
        Object val;
        switch (jsonReader.ch) {
            case '-': case '+': case '0': ... case '.':
                jsonReader.readNumber0();
                val = jsonReader.getNumber();
                break;
            // ... 省略数组、对象、字符串、布尔、null 分支
            default:
                throw new JSONException(jsonReader.info("not support : " + jsonReader.ch));
        }
    }

到这里就完全对上了:

  • reader 被推进到了 traceId 的 第二个字符 r;
  • [0] 段把它当成数组元素的值开始解析;
  • r 不是任何合法 JSON 值的起始字符,进入 default 分支;
  • 抛出 not support : r。

这也解释了为什么报错字符会变:

  • 兄弟字段叫 traceId → 漂移到 r;
  • 兄弟字段叫 remark → 漂移到 e(样例 E);
  • 兄弟字段叫 v(单字符),reader 落到了它的收尾引号 " 上 → 进入字符串解析逻辑,一路读到 EOI,报 invalid escape character EOI(样例 D)。

3.4 样例 B 为什么不报错

样例 B 中 payload 是根对象最后一个字段,后面只剩根对象的收尾 }:

步骤 执行后 jsonReader.ch
couponDetail 段未命中,nextIfObjectEnd() 吃掉 payload 的 } }(根对象的收尾)
JSONPathSegmentName 第 535 行 next() EOI
[0] 段 next() EOI

再看下标段的循环条件:

java 复制代码
for (int i = 0; jsonReader.ch != EOI; ++i)

一开始 ch 就是 EOI,循环一次都不会执行,直接返回 null。

所以 B 的"正常"只是输入结束救了它。换个字段顺序(哪怕只多一个与路径完全无关的兄弟字段),同样的路径就会抛异常。

再补一个边界:没有兄弟字段也不代表一定安全,嵌套深度同样会影响结果。例如:

json 复制代码
{"a":{"b":{"c":{"x":1}}}}

路径 $.a.b.c.missing[0].id 在 2.0.39 下会抛 not support : }(offset 25)------因为在 c 里没找到 missing 后,reader 漂移到了剩余的闭合括号上。所以不要把结论简化成"最后一个字段就一定安全",唯一可靠的判断标准还是:不要用流式 API 去取可能缺失的中间路径。

3.5 为什么换成 .couponDetail.code 不报错

如果把路径改成:

java 复制代码
JSONPath.extract(json, "$.payload.couponDetail.code");

在样例 A 下返回 null,不抛异常。

原因是:couponDetail 未命中后,下一个段是字段名段 。JSONPathSegmentName.accept 在 reader 已经不在对象/数组起始位置时,基本什么都不做就返回;它没有下标段那种"无条件 next() 并把当前位置当值解析"的逻辑,所以不会炸。

本文可稳定复现的危险组合是:

某字段缺失 + 紧随其后的段是 [index] 数组下标。

其它段类型(过滤器、通配符等)是否也有类似问题,本文不展开,但结论不变:不要用流式 API 去取可能缺失的深层路径。

3.6 关键源码位置(fastjson2 2.0.39)

文件 行号 作用
JSONPathMulti.java 327-381 流式求值主循环;344-366 逐段执行,失配时不会停止
JSONPathSegmentName.java 443-603 字段名段;532-548 扫描字段;535 行多走一步
JSONReaderUTF16.java 1018-1065 nextIfObjectEnd() 吃掉 } 及其后的逗号
JSONPathSegmentIndex.java 437-547 下标段;475 无条件 next();477 循环条件;536 抛异常

3.7 版本验证:升级不能解决

用样例 A 在多个 fastjson2 版本上实测:

fastjson2 版本 extract(String, path) eval(Object, path)
2.0.39 ❌ not support : r ✅ null
2.0.43 ❌ not support : r ✅ null
2.0.53 ❌ not support : r ✅ null
2.0.55 ❌ not support : r ✅ null
2.0.61 ❌ not support : r ✅ null

至少在这几个版本范围内,升级 fastjson2 并不能修复这个问题,必须改调用方式。


4. 解决方案

4.1 推荐:先解析成对象,再用 eval(Object, path)

java 复制代码
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONPath;

Object root = JSON.parseObject(json);
Object couponId = JSONPath.eval(root, "$.payload.couponDetail[0].couponId");

System.out.println(couponId); // null,稳定,不抛异常
  • eval(Object, String) 走的是对象求值,不依赖 JSONReader 的位置,缺失的中间节点自然返回 null。
  • 路径存在时同样正常返回,例如样例 C 返回 "C-9"。
  • 注意:必须是 eval(Object, String)。eval(String, String) / extract(String, String) 仍会走流式实现,问题依旧。

如果项目直接使用 fastjson2 API,可以写成:

java 复制代码
Object root = com.alibaba.fastjson2.JSON.parseObject(json);
Object couponId = com.alibaba.fastjson2.JSONPath.eval(root, "$.payload.couponDetail[0].couponId");

4.2 分段取值 + 判空(保留流式性能)

如果报文很大、希望避免整棵解析,可以只对"确定存在的层级"使用流式 extract:

java 复制代码
Object detail = JSONPath.extract(json, "$.payload.couponDetail");
Object couponId = detail == null
        ? null
        : JSONPath.extract(json, "$.payload.couponDetail[0].couponId");

原则:

  • 用 extract 取父级(路径以字段名结尾,不接 [index]);
  • 父级为 null 就直接返回 null;
  • 父级存在后,再取深层路径。

4.3 使用 Jackson / Jayway JsonPath

项目已经引入 Jackson 和 Jayway json-path,也可以用它们的"缺失安全"语义:

java 复制代码
// Jackson:at() 遇到不存在的路径返回 MissingNode,而不是抛异常
JsonNode node = new ObjectMapper()
        .readTree(json)
        .at("/payload/couponDetail/0/couponId");
Object couponId = node.isMissingNode() ? null : node.asText();

Jayway json-path 默认在路径不存在时抛 PathNotFoundException,同样需要显式开启 Option.SUPPRESS_EXCEPTIONS 之类的选项,不能直接裸用。

4.4 封装一个安全取值方法

java 复制代码
public static Object extractOrNull(String json, String path) {
    if (json == null || json.isEmpty()) {
        return null;
    }
    try {
        return JSONPath.eval(JSON.parse(json), path);
    } catch (Exception e) {
        // 生产环境请记录日志,不要无声吞掉
        return null;
    }
}

调用:

java 复制代码
Object couponId = extractOrNull(json, "$.payload.couponDetail[0].couponId");

4.5 方案对比

方案 缺失路径行为 解析成本 建议
extract(String, path) / eval(String, path) 抛异常或"碰巧"返回 null,不可预测 流式,最低 ❌ 不要用于可能缺失的路径
eval(Object, path) 稳定返回 null 全量解析 ✅ 通用首选
分段 extract + 判空 稳定返回 null 流式 ✅ 大报文性能敏感时
Jackson at() 返回 MissingNode 全量解析 ✅ 已有 Jackson 时
Jayway JsonPath 需显式配置缺失策略 全量解析 ⚠️ 注意默认行为

更完整的 API 行为对照和场景选型见第 6 节。


5. 工程建议

5.1 调用侧

  • 不要把 JSONPath.extract(String, path) / eval(String, path) 用在"路径中间可能缺失"的场景。
  • 对可能缺失的中间节点,优先使用 eval(Object, path),或者"先取父级 + 判空 + 再取子级"。
  • 不要用"这次没报错"来证明写法安全------样例 B 已经说明,缺字段也可能返回 null 而不报错,换个字段顺序就会炸。

5.2 测试侧

单元测试至少覆盖以下四类报文,断言缺失路径返回 null 而不是抛异常:

  1. 缺失字段所在对象是最后一个顶层字段(缺失发生在深度 1);
  2. 缺失字段所在对象后面还有兄弟字段;
  3. 兄弟字段名长度不同(1 个字符、多个字符)、兄弟字段值是对象/数组/数字;
  4. 缺失字段嵌套更深且各层都在尾部(验证 3.4 的深度边界)。

第 2 类最容易暴露本文的异常;第 4 类在嵌套深度足够时也会暴露。

5.3 依赖侧

排查项目里 pom.xml 的依赖:

xml 复制代码
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.55</version>
</dependency>
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.39</version>
</dependency>

com.alibaba:fastjson:2.0.55 是兼容包装层,它本身期待配套的 fastjson2 也是 2.0.55;但显式声明的 fastjson2:2.0.39 距离更近,Maven 会选中 2.0.39,形成"2.0.55 包装层 + 2.0.39 内核"的错配。

建议把两者统一到同一版本:

xml 复制代码
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.55</version>
</dependency>
<!-- 删除显式的 fastjson2:2.0.39,让包装层带入 2.0.55 -->

或者显式声明 fastjson2:2.0.55。需要注意:统一版本只能消除依赖错配风险,不能修复本文的流式取值问题。


6. fastjson JSONPath 的多种解析方式与适用场景

6.1 这些 API 是不是"针对不同场景的优化"?

是,但要加一个限定:它们是性能优化,不是语义完全等价的别名。

fastjson 在解析路径字符串时,会根据段数、段类型、目标类型选择不同的实现类;多路径提取还会根据"是否全是字段名 / 是否共享前缀 / 是否全是下标"选择专用实现。目的是减少通用循环里的分支判断、避免构建不必要的对象、支持批量读取。

但这些子类是各写各的读取逻辑,遇到"路径不存在"这类边界时,行为可能分叉。前文的 not support : r 就是 JSONPathMulti 的流式分支暴露出来的实现细节。所以选型时不能只看方法名,要看它背后走的是流式 reader 还是对象模型。

6.2 内部实现如何按路径形状分流

JSONPathParser.parse() 在解析完成后会按段数选择实现(fastjson2 2.0.39,JSONPathParser.java:141-160):

路径形状 内部实现 说明
单段字段名,如 $.a JSONPathSingleName 直接扫描根对象;extract 缺字段返回 null
单段下标,如 $[0] JSONPathSingleIndex 根数组下标
两段,如 $.a.b JSONPathTwoSegment 两段专用流式实现
三段及以上,如 $.a.b[0].c JSONPathMulti 通用分段流式实现,本文异常就出在这里
单段字段名 + Integer/Long/String/BigDecimal JSONPathSingleNameInteger/Long/String/Decimal JSONPathTyped.of() 按目标类型进一步特化(JSONPathTyped.java:85-116)
多路径,全部字段名 JSONPathTypedMultiNames 一次解析提取多个字段
多路径,共享前缀 + 1/2 个字段 JSONPathTypedMultiNamesPrefixName1/2 前缀优化
多路径,每段都是两段式 name+index(如 $.list[0]) JSONPathTypedMultiIndexes 下标优化;父级缺失时实测会抛错
多路径,其他组合 JSONPathTypedMulti 内部 readAny() 后逐路径 eval,缺失返回 null

另外两个和"优化"有关的细节:

  • JSONPath.of(String) 在 2.0.39 没有缓存 ,每次调用都会 new JSONPathParser(path).parse()(JSONPath.java:446-453)。所以高频固定路径应把 JSONPath 实例缓存起来,而不是在循环里反复调用 JSONPath.extract(json, path)。
  • JSONPath.compile(String) 已标记 @Deprecated,等价于 JSONPath.of(path)(JSONPath.java:420-423)。
java 复制代码
// 固定路径:解析一次,反复使用
private static final JSONPath ORDER_NO_PATH = JSONPath.of("$.payload.orderNo");

Object orderNo = ORDER_NO_PATH.eval(root);       // 对象模型,安全
// 或者
Object orderNo2 = ORDER_NO_PATH.extract(json);   // 流式,仍然有缺失路径风险

6.3 各 API 实测对照(fastjson2 2.0.39)

用第 2 节的 A(couponDetail 缺失)和 C(couponDetail 存在)实测:

API A:缺失路径 C:路径存在
extract(String, path) ❌ not support : r ✅ "C-9"
eval(String, path) ❌ 与 extract 相同(内部直接调用 extract) ✅ "C-9"
eval(Object, path) ✅ null ✅ "C-9"
contains(Object, path) ✅ false ✅ true
of(path).extract(String) ❌ not support : r ✅ "C-9"
of(path).eval(Object) ✅ null ✅ "C-9"
of(path, String.class).extract(String) ❌ not support : r ✅ "C-9"
of(path, String.class).eval(Object) ✅ null ✅ "C-9"
of(path).extractScalar(JSONReader) ❌ not support : r ✅ "C-9"(带引号的 JSON 文本)
AlwaysReturnList + extract ❌ not support : r ✅ ["C-9"]
NullOnError + 单路径 extract ❌ 不抑制,仍抛异常 ✅ "C-9"
多路径 typed,字段名型路径 ✅ 对应位置为 null ✅ 对应位置有值
多路径 typed,全部为 name+index 两段路径($.list[0]、$.list[1]) ❌ 父级 list 缺失时抛 illegal input, expect '[' ✅ [1,2]

结论很清晰:

  1. 只要走 eval(Object, ...) 或 contains(Object, ...),缺失路径就是安全的。
  2. 只要走 extract(String/JSONReader/byte[], ...),包括 of(path).extract(...)、typed .extract(...)、extractScalar(...)、AlwaysReturnList,就继承了流式 reader 的风险。
  3. 多路径 typed 也不是无条件安全:字段名型路径表现正常,全部为 name+index 两段路径时,父级缺失会抛错。

6.4 按场景选型

需求 推荐写法 说明
可能缺失的单个字段 JSONPath.eval(JSON.parseObject(json), path) 最稳,缺失返回 null;代价是需要解析整棵树
确定存在、超大报文、只取一两个字段 JSONPath.extract(json, path) 或 JSONPath.of(path).extract(reader) 流式、不构建整棵树;前提是路径确定存在
父级可能缺失,但子路径确定 先 extract 父级判空,再 extract 子路径(本文 4.2) 保留流式;父级路径不要以 [index] 结尾
同一个报文取多个字段 JSON.parseObject 后逐个 eval(Object, path);或字段名型的 of(String[] paths, Type[] types).extract(json) 前者最稳;后者的内部实现按路径形状分流,建议先在本项目的报文上回归
需要类型转换 JSONPath.of(path, Type).eval(object) 或 eval 后手动 cast;不要用 typed .extract(String)
只判断路径是否存在 JSONPath.contains(Object, path) 对象模型,缺失稳定返回 false
需要修改 JSON JSONPath.set/remove(Object, path, ...) 对象模型;set(String, ...) 会 parse 后序列化返回新字符串
高频固定路径 缓存 JSONPath.of(path) 实例 2.0.39 的 of() 不缓存,extract/eval 静态便捷方法每次都会重新解析路径
只需要字符串结果 用 extract/eval 取到值后自行 String.valueOf / JSON.toJSONString 不建议 extractScalar,原因见 6.7

多路径提取示例(字段名型路径,缺失位置返回 null):

java 复制代码
import java.lang.reflect.Type;

JSONPath multi = JSONPath.of(
        new String[]{"$.payload.orderNo", "$.payload.couponDetail[0].couponId"},
        new Type[]{String.class, String.class}
);
Object[] values = (Object[]) multi.extract(json);
// values[0] = "SO202610260001"
// values[1] = null

反例(父级缺失时会抛错,2.0.39 实测):

java 复制代码
// 这两个路径都是两段式 name+index,会走 JSONPathTypedMultiIndexes
JSONPath.of(
        new String[]{"$.list[0]", "$.list[1]"},
        new Type[]{Integer.class, Integer.class}
).extract("{\"other\":[9,9]}");
// JSONException: illegal input, expect '[', but ...

决策流程:

text 复制代码
路径是否可能缺失?
├─ 是 → JSON.parseObject(json) + JSONPath.eval(root, path)      // 最稳
└─ 否 → 追求吞吐:JSONPath.extract(json, path) / 缓存 JSONPath 实例
         追求稳定:JSONPath.eval(root, path)

需要多个字段?
├─ 是 → 解析一次后逐个 eval(最稳)
│        或字段名型多路径 of(paths, types).extract(json)(需回归测试)
└─ 否 → 单路径

需要类型转换?→ typed path 的 eval(Object),不要用 typed 的 extract(String)

6.5 Feature 选项怎么用

JSONPath.Feature 在 2.0.39 只有三个值:

Feature 作用 实测 / 注意
AlwaysReturnList 单值也包装成 JSONArray,便于下游统一处理 extract(C, PATH, AlwaysReturnList) → ["C-9"];缺失路径仍可能抛异常
NullOnError 类型转换失败时置 null 2.0.39 只有 JSONPathTypedMulti 通过 pathFeatures 读取它;单路径传入不会抑制本文的解析异常
KeepNullValue 按字段收集多个值时保留 null,而不是跳过 用于通配/多值收集场景,普通单路径基本用不到

示例:

java 复制代码
// 单值也返回 List,适合结果统一走批量处理
Object v = JSONPath.extract(json, "$.payload.couponDetail[0].couponId",
        JSONPath.Feature.AlwaysReturnList);

6.6 包装层 com.alibaba.fastjson.JSONPath 对照

项目同时引了 com.alibaba:fastjson(兼容包装层)和 fastjson2 内核。包装层的 API 最终都委托到 fastjson2,安全性可以直接对照:

包装层 API 底层走向 缺失路径
extract(String, path) of(path).extract(JSONReader) ❌ 流式问题
eval(String, path) 同上 ❌ 流式问题
read(String, path) / read(String, path, Type) 同上 + 类型转换 ❌ 流式问题
eval(Object, path) of(path).eval(root) ✅ 返回 null
contains(Object, path) 对象求值 ✅ 返回 false
set/remove(...) 对象模型 ✅ 修改类操作,不涉及本文的读取漂移

如果需要 typed path、多路径、Feature 等能力,包装层没有暴露,需要直接使用 com.alibaba.fastjson2.JSONPath。

6.7 三个容易踩的坑

坑 1:extractScalar 不是"安全地把值转成字符串"。

在 2.0.39、2.0.55、2.0.61 上实测,单段字段名路径的 extractScalar 在遇到"目标字段前面的兄弟字段是对象/数组"时会直接返回那个兄弟字段:

json 复制代码
{"a":{},"b":"x"}
java 复制代码
JSONPath.extract(json, "$.b");                                  // "x"
JSONPath.of("$.b").extractScalar(JSONReader.of(json));          // "{}"  ← 错误

本文的订单报文里也有类似现象:$.traceId 的 extractScalar 返回了 payload 对象。因此不要用 extractScalar 做通用取值,需要字符串就自己转换。

坑 2:多路径提取不是无条件安全。

字段名型多路径(如 $.payload.orderNo、$.payload.missing)实测缺失返回 null;但全部为 name+index 两段路径的多路径(如 $.list[0]、$.list[1])在 list 缺失时会走 JSONPathTypedMultiIndexes,抛 illegal input, expect '['。多路径内部会按路径形状自动选择实现,不能假设所有形状都安全。

坑 3:JSONPath.of() 不是缓存工厂。

2.0.39 中它每次都会重新解析路径字符串。高频调用时请自行缓存 JSONPath 实例;否则"复用路径对象"的性能优化等于没做。


附录 A:完整复现代码

java 复制代码
import com.alibaba.fastjson2.JSONPath;

public class Demo {
    public static void main(String[] args) {
        String path = "$.payload.couponDetail[0].couponId";

        // A:payload 后面有兄弟字段 → 抛异常
        String a = "{\"payload\":{\"orderNo\":\"SO202610260001\",\"buyerId\":\"U10086\",\"amount\":199.0,\"couponList\":[{\"couponId\":\"C-1\",\"discount\":10},{\"couponId\":\"C-2\",\"discount\":20}]},\"traceId\":\"tr-9f3c\"}";
        try {
            System.out.println(JSONPath.extract(a, path));
        } catch (Exception e) {
            System.out.println("A => " + e.getMessage());
            // not support : r, offset 158, character r, line 1, column 159
        }

        // B:payload 是最后一个字段 → 返回 null(碰巧不报错)
        String b = "{\"payload\":{\"orderNo\":\"SO202610260001\",\"buyerId\":\"U10086\",\"amount\":199.0,\"couponList\":[{\"couponId\":\"C-1\",\"discount\":10}]}}";
        System.out.println("B => " + JSONPath.extract(b, path)); // null

        // C:路径存在 → 正常返回
        String c = "{\"payload\":{\"couponDetail\":[{\"couponId\":\"C-9\",\"discount\":5}]},\"traceId\":\"tr-9f3c\"}";
        System.out.println("C => " + JSONPath.extract(c, path)); // C-9

        // 推荐写法:先解析成对象再 eval,缺失稳定返回 null
        System.out.println("A eval => " + JSONPath.eval(com.alibaba.fastjson2.JSON.parseObject(a), path)); // null
    }
}

附录 B:源码位置索引(fastjson2 2.0.39)

复制代码
core/src/main/java/com/alibaba/fastjson2/
├── JSONPath.java               # 53-72 静态入口;446-453 of();472-826 多路径;1170-1179 Feature
├── JSONPathParser.java         # 141-160 按路径形状选择 SingleName/TwoSegment/Multi
├── JSONPathTyped.java          # 85-116 类型化路径与单字段类型特化
├── JSONPathTypedMulti.java     # 92-95 多路径 fallback:readAny + eval
├── JSONPathMulti.java          # 流式求值:344-366 逐段执行,失配不终止
├── JSONPathSegmentName.java    # 字段名段:532-548 扫描;535 多一次 next()
├── JSONPathSegmentIndex.java   # 下标段:475 无条件 next();536 default 抛异常
└── JSONReaderUTF16.java        # 1018-1065 nextIfObjectEnd() 连带吃掉逗号

包装层(fastjson 2.0.55)对应代码:

复制代码
com/alibaba/fastjson/JSONPath.java
├── extract(String, String)  # 88-94,委托 fastjson2 流式 extract
├── eval(String, String)     # 52-55,委托 fastjson2 流式 eval
└── eval(Object, String)     # 57-61,委托 fastjson2 对象求值(安全)

一句话总结:不是 JSON 错了,也不是路径写错了,是 JSONPath.extract(String, ...) 在"字段缺失 + 紧跟 [index]"时把 reader 读串位了;改用 eval(Object, ...) 或先取父级判空即可。

相关推荐
星落梦生10 小时前
SpringAOP基础笔记(7)
java·开发语言
金銀銅鐵11 小时前
带您看懂字节码指令(四):一条指令里有什么
java·jvm
最强小杰11 小时前
某 OpenAI 兼容网关上的 `kimi-k3.1-pro`:Cline、Zed 接入与 SSE 排错示例
java·服务器·网络·ai
Flynn Liang12 小时前
流量治理不是限流那么简单:I/O 密集型 Java 服务的 6 层防线
java·微服务·高并发·限流·熔断·系统稳定性·resilience4j
学长毕设12 小时前
基于SpringBoot智慧养老服务平台设计与实现-附源码
java·spring boot·后端
曹牧12 小时前
Java:“刷新雪崩”
java·开发语言
郝学胜-神的一滴12 小时前
Effective STL 条款03:容器中的对象复制要廉价且正确
开发语言·数据结构·c++·算法·rpc·stl
秋天的怀念_David12 小时前
算法一千零一夜 · 第三十三夜 · 跳表
java·程序人生·算法
西西弗Sisyphus13 小时前
C++ explicit 关键字工程实践
开发语言·c++