1. Overview
1.概述
One of the advantages of XML is the availability of processing — including XPath — which is defined as a W3C standard. For JSON, a similar tool called JSONPath has emerged.
XML的优点之一是可以进行处理–包括XPath–它被定义为一个W3C标准。对于JSON，已经出现了一个类似的工具，叫做JSONPath。
This tutorial will give an introduction to Jayway JsonPath, a Java implementation of the JSONPath specification. It describes setup, syntax, common APIs and a demonstration of use cases.
本教程将介绍Jayway JsonPath，这是JSONPath规范的Java实现。它描述了设置、语法、常见的API以及使用案例的演示。
2. Setup
2.设置
To use JsonPath, we simply need to include a dependency in the Maven pom:
要使用JsonPath，我们只需在Maven pom中加入一个依赖项。
<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
<version>2.4.0</version>
</dependency>3. Syntax
3.语法
We’ll use the following JSON structure to demonstrate the syntax and APIs of JsonPath:
我们将使用下面的JSON结构来演示JsonPath的语法和API。
{
"tool":
{
"jsonpath":
{
"creator":
{
"name": "Jayway Inc.",
"location":
[
"Malmo",
"San Francisco",
"Helsingborg"
]
}
}
},
"book":
[
{
"title": "Beginning JSON",
"price": 49.99
},
{
"title": "JSON at Work",
"price": 29.99
}
]
}3.1. Notation
3.1.符号
JsonPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path. There are two styles of notation: dot and bracket.
JsonPath使用特殊的符号来表示JsonPath路径中的节点和它们与相邻节点的连接。有两种记号方式：点和括号。
Both of the following paths refer to the same node from the above JSON document, which is the third element within the location field of creator node, that is a child of the jsonpath object belonging to tool under the root node.
以下两个路径都指向上述JSON文档中的同一个节点，它是creator节点的location字段中的第三个元素，它是根节点下属于tool的jsonpath对象的一个子节点。
First, we’ll see the path with dot notation:
首先，我们来看看用点符号表示的路径。
$.tool.jsonpath.creator.location[2]Now let’s look at bracket notation:
现在我们来看看括号里的符号。
$['tool']['jsonpath']['creator']['location'][2]The dollar sign ($) represents root member object.
美元符号（$）代表根成员对象。
3.2. Operators
3.2.操作人员
We have several helpful operators in JsonPath:
我们在JsonPath中有几个有用的操作符。
- Root node ($) denotes the root member of a JSON structure whether it is an object or array. We included usage examples in the previous subsection.
- Current node (@) represents the node being processed. We mostly use it as part of input expressions for predicates. Suppose we are dealing with book array in the above JSON document; the expression book[?(@.price == 49.99)] refers to the first book in that array.
- Wildcard (*) expresses all elements within the specified scope. For instance, book[*] indicates all nodes inside a book array.
3.3. Functions and Filters
3.3.函数和过滤器
JsonPath also has functions that we can use at the end of a path to synthesize that path’s output expressions: min(), max(), avg(), stddev() and length().
JsonPath也有一些函数，我们可以在路径的末尾使用，以合成该路径的输出表达式。min(), max(), avg(), stddev() 和 length()。
Finally, we have filters. These are boolean expressions to restrict returned lists of nodes to only those that calling methods need.
最后，我们有过滤器。这些是布尔表达式，用来限制返回的节点列表，使其仅为调用方法所需的节点。
A few examples are equality (==), regular expression matching (=~), inclusion (in) and check for emptiness (empty). We mainly use filters for predicates.
几个例子是平等（==）、正则表达式匹配（=~）、包含（in）和检查空性（empty）。我们主要对谓词使用过滤器。
For a full list and detailed explanations of different operators, functions and filters, please refer to the JsonPath GitHub project.
有关不同运算符、函数和过滤器的完整列表和详细解释，请参考JsonPath GitHub项目。
4. Operations
4.操作
Before we get into operations, a quick sidenote: This section makes use of the JSON example structure we defined earlier.
在我们进入操作之前，先说一下注意事项：本节使用了我们之前定义的JSON示例结构。
4.1. Access to Documents
4.1.查阅文件
JsonPath has a convenient way to access JSON documents. We do this through static read APIs:
JsonPath有一个方便的方法来访问JSON文档。我们通过静态的read APIs来实现。
<T> T JsonPath.read(String jsonString, String jsonPath, Predicate... filters);The read APIs can work with static fluent APIs to provide more flexibility:
read API可以与静态流畅的API合作，提供更多的灵活性。
<T> T JsonPath.parse(String jsonString).read(String jsonPath, Predicate... filters);We can use other overloaded variants of read for different types of JSON sources, including Object, InputStream, URL and File.
我们可以对不同类型的JSON源使用read的其他重载变体，包括Object、InputStream、URL和File。
To make things simple, the test for this part does not include predicates in the parameter list (empty varargs). But we’ll discuss predicates in later subsections.
为了简单起见，这部分的测试不包括参数列表中的谓词（空varargs）。但我们将在后面的小节中讨论谓词。
Let’s start by defining two sample paths to work on:
让我们首先定义两个样本路径来进行工作。
String jsonpathCreatorNamePath = "$['tool']['jsonpath']['creator']['name']";
String jsonpathCreatorLocationPath = "$['tool']['jsonpath']['creator']['location'][*]";Next, we will create a DocumentContext object by parsing the given JSON source jsonDataSourceString. The newly created object will then be used to read content using the paths defined above:
接下来，我们将通过解析给定的JSON源jsonDataSourceString，创建一个DocumentContext对象。然后，新创建的对象将被用于使用上面定义的路径来读取内容。
DocumentContext jsonContext = JsonPath.parse(jsonDataSourceString);
String jsonpathCreatorName = jsonContext.read(jsonpathCreatorNamePath);
List<String> jsonpathCreatorLocation = jsonContext.read(jsonpathCreatorLocationPath);The first read API returns a String containing the name of the JsonPath creator, while the second returns a list of its addresses.
第一个read API返回一个String，包含JsonPath创建者的名字，而第二个则返回其地址的列表。
And we’ll use the JUnit Assert API to confirm the methods work as expected:
我们将使用JUnit的Assert API来确认这些方法按预期工作。
assertEquals("Jayway Inc.", jsonpathCreatorName);
assertThat(jsonpathCreatorLocation.toString(), containsString("Malmo"));
assertThat(jsonpathCreatorLocation.toString(), containsString("San Francisco"));
assertThat(jsonpathCreatorLocation.toString(), containsString("Helsingborg"));4.2. Predicates
4.2.谓词
Now that we have the basics, let’s define a new JSON example to work on and illustrate how to create and use predicates:
现在我们有了基础知识，让我们定义一个新的JSON例子来工作，说明如何创建和使用谓词。
{
"book":
[
{
"title": "Beginning JSON",
"author": "Ben Smith",
"price": 49.99
},
{
"title": "JSON at Work",
"author": "Tom Marrs",
"price": 29.99
},
{
"title": "Learn JSON in a DAY",
"author": "Acodemy",
"price": 8.99
},
{
"title": "JSON: Questions and Answers",
"author": "George Duckett",
"price": 6.00
}
],
"price range":
{
"cheap": 10.00,
"medium": 20.00
}
}Predicates determine true or false input values for filters to narrow down returned lists to only matched objects or arrays. We can easily integrate a Predicate into a Filter by using it as an argument for its static factory method. The requested content can then be read out of a JSON string using that Filter:
谓词确定过滤器的真假输入值，将返回的列表缩小到只匹配对象或数组。我们可以轻松地将Predicate集成到Filter中，方法是将其作为静态工厂方法的一个参数。然后可以使用该Filter从JSON字符串中读出请求的内容。
Filter expensiveFilter = Filter.filter(Criteria.where("price").gt(20.00));
List<Map<String, Object>> expensive = JsonPath.parse(jsonDataSourceString)
.read("$['book'][?]", expensiveFilter);
predicateUsageAssertionHelper(expensive);We could also define our customized Predicate and use it as an argument for the read API:
我们也可以定义我们自定义的Predicate并将其作为read API的参数。
Predicate expensivePredicate = new Predicate() {
public boolean apply(PredicateContext context) {
String value = context.item(Map.class).get("price").toString();
return Float.valueOf(value) > 20.00;
}
};
List<Map<String, Object>> expensive = JsonPath.parse(jsonDataSourceString)
.read("$['book'][?]", expensivePredicate);
predicateUsageAssertionHelper(expensive);Finally, a predicate can be directly applied to read API without the creation of any objects, which is called inline predicate:
最后，一个谓词可以直接应用于read API，而无需创建任何对象，这被称为内联谓词。
List<Map<String, Object>> expensive = JsonPath.parse(jsonDataSourceString)
.read("$['book'][?(@['price'] > $['price range']['medium'])]");
predicateUsageAssertionHelper(expensive);All three of the Predicate examples above are verified with the help of the following assertion helper method:
上面的三个Predicate 例子都是在以下断言辅助方法的帮助下验证的。
private void predicateUsageAssertionHelper(List<?> predicate) {
assertThat(predicate.toString(), containsString("Beginning JSON"));
assertThat(predicate.toString(), containsString("JSON at Work"));
assertThat(predicate.toString(), not(containsString("Learn JSON in a DAY")));
assertThat(predicate.toString(), not(containsString("JSON: Questions and Answers")));
}5. Configuration
5.配置
5.1. Options
5.1.选项
Jayway JsonPath provides several options to tweak the default configuration:
Jayway JsonPath提供了几个选项来调整默认配置。
- Option.AS_PATH_LIST returns paths of the evaluation hits instead of their values.
- Option.DEFAULT_PATH_LEAF_TO_NULL returns null for missing leaves.
- Option.ALWAYS_RETURN_LIST returns a list even when the path is definite.
- Option.SUPPRESS_EXCEPTIONS makes sure no exceptions are propagated from path evaluation.
- Option.REQUIRE_PROPERTIES requires properties defined in the path when an indefinite path is evaluated.
Here is how to apply Option from scratch:
下面是如何从头开始应用Option。
Configuration configuration = Configuration.builder().options(Option.<OPTION>).build();and how to add it to an existing configuration:
以及如何将其添加到现有配置中。
Configuration newConfiguration = configuration.addOptions(Option.<OPTION>);5.2. SPIs
5.2. SPI
JsonPath’s default configuration with the help of Option should be enough for the majority of tasks. However, users with more complex use cases can modify the behavior of JsonPath according to their specific requirements — using three different SPIs:
JsonPath的默认配置在Option的帮助下应该足以满足大多数任务的需要。然而，有更复杂用例的用户可以根据他们的具体要求修改JsonPath的行为 – 使用三个不同的SPI。
- JsonProvider SPI lets us change the ways JsonPath parses and handles JSON documents.
- MappingProvider SPI allows for customization of bindings between node values and returned object types.
- CacheProvider SPI adjusts the manners that paths are cached, which can help to increase performance.
6. Example Use Cases
6.用例
We now have a good understanding of the JsonPath functionality. So, let’s look at an example.
我们现在对JsonPath的功能有了很好的理解。那么，让我们看一个例子。
This section illustrates dealing with JSON data returned from a web service.
本节说明了如何处理从网络服务返回的JSON数据。
Assume we have a movie information service that returns the following structure:
假设我们有一个电影信息服务，返回以下结构。
[
{
"id": 1,
"title": "Casino Royale",
"director": "Martin Campbell",
"starring":
[
"Daniel Craig",
"Eva Green"
],
"desc": "Twenty-first James Bond movie",
"release date": 1163466000000,
"box office": 594275385
},
{
"id": 2,
"title": "Quantum of Solace",
"director": "Marc Forster",
"starring":
[
"Daniel Craig",
"Olga Kurylenko"
],
"desc": "Twenty-second James Bond movie",
"release date": 1225242000000,
"box office": 591692078
},
{
"id": 3,
"title": "Skyfall",
"director": "Sam Mendes",
"starring":
[
"Daniel Craig",
"Naomie Harris"
],
"desc": "Twenty-third James Bond movie",
"release date": 1350954000000,
"box office": 1110526981
},
{
"id": 4,
"title": "Spectre",
"director": "Sam Mendes",
"starring":
[
"Daniel Craig",
"Lea Seydoux"
],
"desc": "Twenty-fourth James Bond movie",
"release date": 1445821200000,
"box office": 879376275
}
]where the value of release date field is milliseconds since the Epoch, and box office is revenue of a movie in the cinema in US dollars.
其中release date字段的值是自大纪元以来的毫秒数，box office是一部电影在电影院的收入，以美元计。
We are going to handle five different working scenarios related to GET requests, supposing that the above JSON hierarchy has been extracted and stored in a String variable named jsonString.
我们将处理五个与GET请求有关的不同工作场景，假设上述JSON层次结构已被提取并存储在一个名为jsonString的变量中。
6.1. Getting Object Data Given IDs
6.1.获取给定ID的对象数据
In this use case, a client requests detailed information on a specific movie by providing the server with the movie’s exact id. This example demonstrates how the server looks for requested data before returning to the client.
在这个用例中，一个客户通过向服务器提供电影的确切id来请求关于一部特定电影的详细信息。这个例子演示了服务器在返回给客户之前如何寻找所请求的数据。
Say we need to find a record with id equaling to 2.
假设我们需要找到一条id等于2的记录。
The first step is to pick up the correct data object:
第一步是拿起正确的数据对象。
Object dataObject = JsonPath.parse(jsonString).read("$[?(@.id == 2)]");
String dataString = dataObject.toString();The JUnit Assert API confirms the existence of several fields:
JUnit Assert API确认了几个字段的存在。
assertThat(dataString, containsString("2"));
assertThat(dataString, containsString("Quantum of Solace"));
assertThat(dataString, containsString("Twenty-second James Bond movie"));6.2. Getting the Movie Title Given Starring
6.2.获得电影名称的主演
Let’s say we want to look for a movie starring an actress called Eva Green. The server needs to return title of the movie that includes Eva Green in the starring array.
假设我们想寻找一部由一个叫Eva Green的女演员主演的电影。服务器需要返回title中包含Eva Green的电影的starring数组。
The succeeding test will illustrate how to do that and validate the returned result:
接下来的测试将说明如何做到这一点并验证返回的结果。
@Test
public void givenStarring_whenRequestingMovieTitle_thenSucceed() {
List<Map<String, Object>> dataList = JsonPath.parse(jsonString)
.read("$[?('Eva Green' in @['starring'])]");
String title = (String) dataList.get(0).get("title");
assertEquals("Casino Royale", title);
}6.3. Calculation of the Total Revenue
6.3.总收入的计算
This scenario makes use of a JsonPath function called length() to figure out the number of movie records in order to calculate the total revenue of all the movies.
这个方案利用一个名为length()的JsonPath函数来计算出电影记录的数量，以便计算出所有电影的总收入。
Let’s look at the implementation and testing:
让我们来看看实施和测试情况。
@Test
public void givenCompleteStructure_whenCalculatingTotalRevenue_thenSucceed() {
DocumentContext context = JsonPath.parse(jsonString);
int length = context.read("$.length()");
long revenue = 0;
for (int i = 0; i < length; i++) {
revenue += context.read("$[" + i + "]['box office']", Long.class);
}
assertEquals(594275385L + 591692078L + 1110526981L + 879376275L, revenue);
}6.4. Highest Revenue Movie
6.4.收入最高的电影
This use case exemplifies the usage of a non-default JsonPath configuration option, namely Option.AS_PATH_LIST, to find out the movie with the highest revenue.
这个用例说明了一个非默认的JsonPath配置选项，即Option.AS_PATH_LIST的用法，以找出收入最高的电影。
First, we need to extract a list of all the movies’ box office revenue. Then we convert it to an array for sorting:
首先，我们需要提取一个所有电影票房收入的列表。然后我们把它转换成一个数组进行排序。
DocumentContext context = JsonPath.parse(jsonString);
List<Object> revenueList = context.read("$[*]['box office']");
Integer[] revenueArray = revenueList.toArray(new Integer[0]);
Arrays.sort(revenueArray);We can easily pick up the highestRevenue variable from the revenueArray sorted array and then use it for working out the path to the movie record with the highest revenue:
我们可以很容易地从revenueArray排序数组中拾取highestRevenue变量，然后用它来计算通往收入最高的电影记录的路径。
int highestRevenue = revenueArray[revenueArray.length - 1];
Configuration pathConfiguration =
Configuration.builder().options(Option.AS_PATH_LIST).build();
List<String> pathList = JsonPath.using(pathConfiguration).parse(jsonString)
.read("$[?(@['box office'] == " + highestRevenue + ")]");Based on that calculated path, we’ll determine and return the title of the corresponding movie:
基于该计算路径，我们将确定并返回相应电影的title。
Map<String, String> dataRecord = context.read(pathList.get(0));
String title = dataRecord.get("title");The whole process is verified by the Assert API:
整个过程由Assert API进行验证。
assertEquals("Skyfall", title);6.5. Latest Movie of a Director
6.5 一个导演的最新电影
This example will illustrate how to figure out the last movie directed by a director named Sam Mendes.
这个例子将说明如何计算出一个名叫Sam Mendes的导演所导演的最后一部电影。
To begin with, we create a list of all the movies directed by Sam Mendes:
首先，我们创建一个由Sam Mendes执导的所有电影列表。
DocumentContext context = JsonPath.parse(jsonString);
List<Map<String, Object>> dataList = context.read("$[?(@.director == 'Sam Mendes')]");We then use that list for extraction of release dates. Those dates will be stored in an array and then sorted:
然后我们使用该列表来提取发布日期。这些日期将被存储在一个数组中，然后进行排序。
List<Object> dateList = new ArrayList<>();
for (Map<String, Object> item : dataList) {
Object date = item.get("release date");
dateList.add(date);
}
Long[] dateArray = dateList.toArray(new Long[0]);
Arrays.sort(dateArray);We use the lastestTime variable (the last element of the sorted array) in combination with the director field’s value to determine the title of the requested movie:
我们使用lastestTime变量（排序数组的最后一个元素）结合director字段的值来确定请求的电影的title。
long latestTime = dateArray[dateArray.length - 1];
List<Map<String, Object>> finalDataList = context.read("$[?(@['director']
== 'Sam Mendes' && @['release date'] == " + latestTime + ")]");
String title = (String) finalDataList.get(0).get("title");The following assertion proves that everything works as expected:
下面的论断证明，一切都按预期进行。
assertEquals("Spectre", title);7. Conclusion
7.结论
This article covered fundamental features of Jayway JsonPath — a powerful tool to traverse and parse JSON documents.
本文介绍了Jayway JsonPath的基本功能–一个强大的工具，用于遍历和解析JSON文档。
Although JsonPath has some drawbacks, such as a lack of operators for reaching parent or sibling nodes, it can be highly useful in a lot of scenarios.
虽然JsonPath有一些缺点，比如缺乏到达父节点或兄弟节点的操作符，但它在很多情况下都非常有用。
The implementation of all these examples and code snippets can be found over on GitHub.
所有这些例子和代码片断的实现都可以在GitHub上找到over。