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 从矩阵里读出三件事
- 是否报错,取决于 reader 漂移后落到的字符:通常与缺失字段所在对象后面还有没有兄弟字段、以及还剩几层闭合括号有关;与路径本身、与 JSON 是否合法都无关。
- 报错字符和异常类型也不固定 :A 是
r,E 是e,D 是另一种错误。因为 reader 漂移后碰到的 token 不同,解析器只能"遇到什么报什么"。 - 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:javaif (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 个字符、多个字符)、兄弟字段值是对象/数组/数字;
- 缺失字段嵌套更深且各层都在尾部(验证 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] |
结论很清晰:
- 只要走
eval(Object, ...)或contains(Object, ...),缺失路径就是安全的。 - 只要走
extract(String/JSONReader/byte[], ...),包括of(path).extract(...)、typed.extract(...)、extractScalar(...)、AlwaysReturnList,就继承了流式 reader 的风险。 - 多路径 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, ...) 或先取父级判空即可。