分页和排序
本节介绍 Spring Data REST 如何使用 Spring Data 存储库的分页和排序抽象。要熟悉这些功能,请参阅您使用的存储库实现的 Spring Data 文档(例如 Spring Data JPA)。
分页
Spring Data REST 不会返回大型结果集中的所有内容,而是识别一些会影响页面大小和起始页码的 URL 参数。
如果您扩展了 PagingAndSortingRepository<T, ID>
并访问所有实体的列表,则会获得指向前 20 个实体的链接。要将页面大小设置为任何其他数字,请添加 size
参数,如下所示
https://127.0.0.1:8080/people/?size=5
以上示例将页面大小设置为 5。
要在您自己的查询方法中使用分页,您需要更改方法签名以接受额外的 Pageable
参数并返回 Page
或 Slice
而不是 List
。例如,以下查询方法导出到 /people/search/nameStartsWith
并支持分页
@RestResource(path = "nameStartsWith", rel = "nameStartsWith")
public Page findByNameStartsWith(@Param("name") String name, Pageable p);
Spring Data REST 导出器识别返回的 Page
/Slice
并将结果显示在响应的主体中,就像处理非分页响应一样,但会在资源中添加其他链接来表示数据的前一页和下一页。
前一页和下一页链接
每个分页响应都会根据当前页面使用 IANA 定义的链接关系 prev
和 next
返回指向结果前一页和下一页的链接。但是,如果您当前位于结果的第一页,则不会呈现 prev
链接。对于最后一页结果,不会呈现 next
链接。
考虑以下示例,其中我们将页面大小设置为 5
curl localhost:8080/people?size=5
{
"_links" : {
"self" : {
"href" : "https://127.0.0.1:8080/persons{&sort,page,size}", (1)
"templated" : true
},
"next" : {
"href" : "https://127.0.0.1:8080/persons?page=1&size=5{&sort}", (2)
"templated" : true
}
},
"_embedded" : {
… data …
},
"page" : { (3)
"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 0
}
}
在顶部,我们看到 _links
1 | self 链接会提供整个集合以及一些选项。 |
2 | next 链接指向下一页,假设页面大小相同。 |
3 | 底部是关于页面设置的额外数据,包括页面大小、总元素数、总页数以及您当前正在查看的页码。 |
在命令行上使用 curl 等工具时,如果语句中包含与号 (& ),则需要将整个 URI 括在引号中。 |
请注意,self
和 next
URI 实际上是 URI 模板。它们不仅接受 size
,还接受 page
和 sort
作为可选标志。
如前所述,HAL 文档的底部包含有关页面的详细信息集合。此额外信息使您可以轻松配置 UI 工具(如滑块或指示器)以反映用户在查看数据时的整体位置。例如,前面示例中的文档显示我们正在查看第一页(页码从 0 开始)。
以下示例显示了遵循 next
链接时会发生什么
$ curl "https://127.0.0.1:8080/persons?page=1&size=5"
{
"_links" : {
"self" : {
"href" : "https://127.0.0.1:8080/persons{&sort,projection,page,size}",
"templated" : true
},
"next" : {
"href" : "https://127.0.0.1:8080/persons?page=2&size=5{&sort,projection}", (1)
"templated" : true
},
"prev" : {
"href" : "https://127.0.0.1:8080/persons?page=0&size=5{&sort,projection}", (2)
"templated" : true
}
},
"_embedded" : {
... data ...
},
"page" : {
"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 1 (3)
}
}
这看起来非常相似,但以下差异除外
1 | next 链接现在指向另一页,表明它相对于 self 链接的相对位置。 |
2 | 现在出现了 prev 链接,为我们提供了返回上一页的路径。 |
3 | 当前数字现在是 1(表示第二页)。 |
此功能允许您将屏幕上的可选按钮映射到这些超媒体控件,从而允许您为 UI 体验实现导航功能,而无需硬编码 URI。实际上,用户可以从页面大小列表中进行选择,动态更改提供的内容,而无需重写顶部或底部的 next
和 prev
控件。
排序
Spring Data REST 识别使用存储库排序支持的排序参数。
要根据特定属性对结果进行排序,请添加一个 sort
URL 参数,其中包含要对其排序结果的属性的名称。您可以通过在属性名称后附加逗号 (,
) 以及 asc
或 desc
来控制排序方向。以下示例将使用在 PersonRepository
上定义的 findByNameStartsWith
查询方法查找名称以字母“K”开头的所有 Person
实体,并添加排序数据,以便按 name
属性降序排列结果
curl -v "https://127.0.0.1:8080/people/search/nameStartsWith?name=K&sort=name,desc"
要按多个属性对结果进行排序,请根据需要继续添加尽可能多的 sort=PROPERTY
参数。它们会按照它们在查询字符串中出现的顺序添加到 Pageable
中。结果可以按顶级属性和嵌套属性进行排序。使用属性路径表示法来表达嵌套排序属性。不支持按可链接关联(即指向顶级资源的链接)排序。