JsonPath 表达式核心用法与实战指南

实战示例

假设我们有如下 JSON 数据：

{
  "store": {
    "book": [
      { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 },
      { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 },
      { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 },
      { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 }
    ],
    "bicycle": { "color": "red", "price": 19.95 }
  },
  "expensive": 10
}

常用 API 模式

通常直接使用静态方法 API 进行调用：

String json = "...";
List<String> authors = JsonPath.read(json, "$.store.book[*].author");

这种方式适合单次解析。如果需要对同一个 JSON 解析多次，不建议重复调用 read，因为每次都会重新解析。此时建议使用 ReadContext 或 WriteContext：

String json = "...";
ReadContext ctx = JsonPath.parse(json);
List<String> authorsOfBooksWithISBN = ctx.read("$.store.book[?(@.isbn)].author");

// 使用配置构建器
List<Map<String, Object>> expensiveBooks = JsonPath
    .using(configuration)
    .parse(json)
    .read("$.store.book[?(@.price > 10)]", List.class);

返回值与类型转换

read 后的返回值会自动转型到指定类型。对于明确定义的表达式，应指定对应类型；对于含糊表达式（包含 ..、?[...] 等），通常应使用数组接收。如需转换成具体类型，可通过 configuration 配置 mappingProvider：

String json = "{\"date_as_long\" : 1411455611975}";
Date date = JsonPath.parse(json).read("$['date_as_long']", Date.class); // 使用 JsonSmartMappingProvider
Book book = JsonPath.parse(json).read("$.store.book[0]", Book.class); // 使用 GsonMappingProvider

自定义映射提供者

JsonPath 支持 SPI 扩展反序列化器。默认使用 JsonSmartMappingProvider，它注册了基本数据类型的转换逻辑。若需切换 Provider（例如使用 Jackson），可配置如下：

Configuration.setDefaults(new Configuration.Defaults() {
    private final JsonProvider jsonProvider = new JacksonJsonProvider();
    private final MappingProvider mappingProvider = new JacksonMappingProvider();

    @Override public JsonProvider jsonProvider() { return jsonProvider; }
    @Override public MappingProvider mappingProvider() { return mappingProvider; }
    @Override public Set<Option> options() { return EnumSet.noneOf(Option.class); }
});

断言谓词实现

创建过滤器断言有三种方式：

1. Inline Predicates

直接在表达式中使用 ?[<@expression>]：

List<Map<String, Object>> books = JsonPath.parse(json)
    .read("$.store.book[?(@.price < 10)]");

2. Filter API

使用 Filter 类构建复杂逻辑：

import static com.jayway.jsonpath.JsonPath.parse;
import static com.jayway.jsonpath.Criteria.where;
import static com.jayway.jsonpath.Filter.filter;

Filter cheapFictionFilter = filter(
    where("category").is("fiction").and("price").lte(10D)
);
List<Map<String, Object>> books = parse(json).read("$.store.book[?]", cheapFictionFilter);

// 支持 or 和 and 组合
Filter fooOrBar = filter(where("foo").exists(true)).or(where("bar").exists(true));

注意：表达式中必须有占位符 ?，多个占位符会按顺序替换。

3. 自定义 Predicate

实现 Predicate 接口处理特殊逻辑：

Predicate booksWithISBN = new Predicate() {
    @Override
    public boolean apply(PredicateContext ctx) {
        return ctx.item(Map.class).containsKey("isbn");
    }
};
List<Map<String, Object>> books = reader.read("$.store.book[?].isbn", List.class, booksWithISBN);

获取路径列表

有时需要获取匹配到的完整路径而非值，可使用 AS_PATH_LIST 选项：

Configuration conf = Configuration.builder()
    .options(Option.AS_PATH_LIST)
    .build();
List<String> pathList = using(conf).parse(json).read("$..author");
// 结果示例：
// "$['store']['book'][0]['author']"
// "$['store']['book'][1]['author']"

配置选项详解

DEFAULT_PATH_LEAF_TO_NULL

检索不到时返回 null 而不是抛出异常。默认行为是抛出 PathNotFoundException。

Configuration conf2 = conf.addOptions(Option.DEFAULT_PATH_LEAF_TO_NULL);
String gender1 = JsonPath.using(conf2).parse(json).read("$[1]['gender']"); // 返回 null

ALWAYS_RETURN_LIST

总是返回 List，即使结果是单个非 List 类型也会被包装。

SUPPRESS_EXCEPTIONS

不抛出异常。开启 ALWAYS_RETURN_LIST 时返回空 List，否则返回 null。

AS_PATH_LIST

返回路径列表（见上文）。

REQUIRE_PROPERTIES

禁止使用通配符，否则抛出异常。

缓存机制

每次 read 都会尝试获取缓存以提高性能，但默认未启用。JsonPath 2.1.0+ 提供了新的 SPI 缓存实现：

• NOOPCache: 无缓存
• LRUCache: 默认实现，线程安全

如需自定义缓存：

CacheProvider.setCache(new Cache() {
    private Map<String, JsonPath> map = new HashMap<>();
    @Override public JsonPath get(String key) { return map.get(key); }
    @Override public void put(String key, JsonPath jsonPath) { map.put(key, jsonPath); }
});