怎么用 Spring Data 在 RESTful API 中实现更好的分页

介绍

本文将重点介绍如何使用 Spring MVC 和 Spring Data 在 RESTful API 中实现分页。

REST 分页的可发现性

在分页范围内，知足 REST 的 HATEOAS 约束，意味着使 API 的客户端可以基于导航中的当前页面发现下一页和上一页。 为此，咱们将使用Link HTTP 响应头，以及 “next”，“prev”，“first” 和 “last” 连接关系类型。
添加一个侦听器，监听器将检查导航是否容许下一页，上一页，第一页和最后一页。它将相关的 URI 做为 “连接” 添加到 HTTP 响应头中。

void addLinkHeaderOnPagedResourceRetrieval(
  UriComponentsBuilder uriBuilder, HttpServletResponse response,
  Class clazz, int page, int totalPages, int size ){
 
    String resourceName = clazz.getSimpleName().toString().toLowerCase();
    uriBuilder.path( "/admin/" + resourceName );
 
    // ...
    
}

接下来，咱们将使用 StringJoiner 链接每一个连接。咱们将使用 uriBuilder 生成 uri。让咱们看看咱们如何继续连接到下一页：

StringJoiner linkHeader = new StringJoiner(", ");
if (hasNextPage(page, totalPages)){
    String uriForNextPage = constructNextPageUri(uriBuilder, page, size);
    linkHeader.add(createLinkHeader(uriForNextPage, "next"));
}

让咱们来看看 constructNextPageUri 方法的逻辑：

String constructNextPageUri(UriComponentsBuilder uriBuilder, int page, int size) {
    return uriBuilder.replaceQueryParam(PAGE, page + 1)
      .replaceQueryParam("size", size)
      .build()
      .encode()
      .toUriString();
}

咱们将对但愿包含的其他 uri 进行相似的处理。
最后，咱们将输出添加为响应头：

response.addHeader("Link", linkHeader.toString());

测试分页

代码以下：

@Test
public void whenResourcesAreRetrievedPaged_then200IsReceived(){
    Response response = RestAssured.get(paths.getFooURL() + "?page=0&size=2");
 
    assertThat(response.getStatusCode(), is(200));
}
@Test
public void whenPageOfResourcesAreRetrievedOutOfBounds_then404IsReceived(){
    String url = getFooURL() + "?page=" + randomNumeric(5) + "&size=2";
    Response response = RestAssured.get.get(url);
 
    assertThat(response.getStatusCode(), is(404));
}
@Test
public void givenResourcesExist_whenFirstPageIsRetrieved_thenPageContainsResources(){
   createResource();
   Response response = RestAssured.get(paths.getFooURL() + "?page=0&size=2");
 
   assertFalse(response.body().as(List.class).isEmpty());
}

测试分页的可发现性

测试的重点是当前页面在导航中的位置，以及应该从每一个位置发现的不一样 uri：

@Test
public void whenFirstPageOfResourcesAreRetrieved_thenSecondPageIsNext(){
   Response response = RestAssured.get(getFooURL()+"?page=0&size=2");
 
   String uriToNextPage = extractURIByRel(response.getHeader("Link"), "next");
   assertEquals(getFooURL()+"?page=1&size=2", uriToNextPage);
}
@Test
public void whenFirstPageOfResourcesAreRetrieved_thenNoPreviousPage(){
   Response response = RestAssured.get(getFooURL()+"?page=0&size=2");
 
   String uriToPrevPage = extractURIByRel(response.getHeader("Link"), "prev");
   assertNull(uriToPrevPage );
}
@Test
public void whenSecondPageOfResourcesAreRetrieved_thenFirstPageIsPrevious(){
   Response response = RestAssured.get(getFooURL()+"?page=1&size=2");
 
   String uriToPrevPage = extractURIByRel(response.getHeader("Link"), "prev");
   assertEquals(getFooURL()+"?page=0&size=2", uriToPrevPage);
}
@Test
public void whenLastPageOfResourcesIsRetrieved_thenNoNextPageIsDiscoverable(){
   Response first = RestAssured.get(getFooURL()+"?page=0&size=2");
   String uriToLastPage = extractURIByRel(first.getHeader("Link"), "last");
 
   Response response = RestAssured.get(uriToLastPage);
 
   String uriToNextPage = extractURIByRel(response.getHeader("Link"), "next");
   assertNull(uriToNextPage);
}

使用 Spring Data 实现 REST 分页

在 Spring Data 中，若是咱们须要从完整的结果集中返回一些结果，则可使用任何 Pageable 存储库方法，由于它将始终返回 Page。 将根据页码，页面大小和排序方向返回结果。
Spring Data REST 自动识别 URL 参数，例如页码，页面大小，排序等。
要使用任何存储库的分页方法，咱们须要扩展 PagingAndSortingRepository：

public interface SubjectRepository extends PagingAndSortingRepository<Subject, Long>{}

若是咱们调用 localhost:8080/subjects Spring 会自动添加页码，页面大小，排序参数：

"_links" : {
  "self" : {
    "href" : "http://localhost:8080/subjects{?page,size,sort}",
    "templated" : true
  }
}

默认状况下，页面大小是20，可是咱们能够经过调用相似于 localhost:8080/subject?page=10 这样的东西来更改它。
若是咱们想实现分页到咱们本身的自定义库 API，咱们须要传递一个额外的可分页参数，并确保 API 返回一个 Page：

@RestResource(path = "nameContains")
public Page<Subject> findByNameContaining(@Param("name") String name, Pageable p);

每当咱们添加自定义API时，就会将 /search 端点添加到生成的连接中。所以，若是咱们调用 localhost:8080/subjects/search，咱们将看到一个分页功能的端点：

"findByNameContaining" : {
  "href" : "http://localhost:8080/subjects/search/nameContains{?name,page,size,sort}",
  "templated" : true
}

全部实现 PagingAndSortingRepository 的 api 都将返回一个页面。若是咱们须要返回来自页面的结果列表，页面的 getContent() API 提供了做为 Spring Data REST API 的结果而获取的记录列表。

将 List 转换为 Page

假设咱们有一个可分页的对象做为输入，可是咱们须要检索的信息包含在一个 List 中，而不是一个 PagingAndSortingRepository。在这些状况下，咱们可能须要将 List 转换为 Page。
例如，假设咱们有一个 SOAP 服务的结果列表：

List<Foo> list = getListOfFooFromSoapService();

咱们须要在发送给咱们的 Pageable 对象指定的特定位置访问列表。那么，让咱们定义开始索引：

int start = (int) pageable.getOffset();

结束索引：

int end = (int) ((start + pageable.getPageSize()) > fooList.size() ? fooList.size()
  : (start + pageable.getPageSize()));

有了这两个地方，咱们能够建立一个 Page 来获取它们之间的元素列表：

Page<Foo> page = new PageImpl<Foo>(fooList.subList(start, end), pageable, fooList.size());

这样咱们就能够返回 Page 做为一个有效的结果。
注意，若是咱们还但愿支持排序，咱们须要在将 List 的子列表以前对其进行排序。

总结

本文演示了如何使用 Spring 在 REST API 中实现分页，并讨论了如何设置和测试可发现性。

欢迎关注个人公众号：曲翎风，得到独家整理的学习资源和平常干货推送。
若是您对个人专题内容感兴趣，也能够关注个人博客： sagowiec.com