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