使用Spring 在 REST API 中实现分页

2016-01-13 2821 words 6 minutes

Contents

1. 概述

本教程将重点介绍使用 Spring MVC 和 Spring Data 在 REST API 中实现分页。

2. 页面作为资源与页面作为表示

在 RESTful 架构的上下文中设计分页时的第一个问题是，是否将页面视为实际资源或只是资源的表示。将页面本身视为资源会引入许多问题，例如不再能够在调用之间唯一标识资源。这一点，再加上在持久层中，页面不是一个适当的实体，而是一个在必要时构建的持有者，这使得选择变得简单；页面是表示的一部分。

REST 上下文中分页设计的下一个问题是在哪里包含分页信息：

在 URI 路径中：/foo/page/1
URI 查询：/foo?page=1

请记住，页面不是 Resource，因此无法在 URI 中编码页面信息。

我们将使用标准方法通过在 URI 查询中编码分页信息来解决这个问题。

3. 控制器

现在进行实施。用于分页的 Spring MVC 控制器很简单：

@GetMapping(params = { "page", "size" })
public List<Foo> findPaginated(@RequestParam("page") int page, 
  @RequestParam("size") int size, UriComponentsBuilder uriBuilder,
  HttpServletResponse response) {
    Page<Foo> resultPage = service.findPaginated(page, size);
    if (page > resultPage.getTotalPages()) {
        throw new MyResourceNotFoundException();
    }
    eventPublisher.publishEvent(new PaginatedResultsRetrievedEvent<Foo>(
      Foo.class, uriBuilder, response, page, resultPage.getTotalPages(), size));
    return resultPage.getContent();
}

在本例中，我们通过*@RequestParam在 Controller 方法中注入两个查询参数size和page*。 **或者，我们可以使用Pageable对象，它自动映射page、 size和 sort参数。**此外，PagingAndSortingRepository实体提供了开箱即用的方法，支持使用Pageable作为参数。

我们还注入了 Http Response 和UriComponentsBuilder来帮助实现可发现性，我们通过自定义事件将其解耦。如果这不是 API 的目标，我们可以简单地删除自定义事件。

4. REST 分页的可发现性

在分页范围内，满足REST 的 HATEOAS 约束意味着 API 的客户端能够根据导航中的当前页面发现下一页和上一页。为此，我们将使用Link HTTP 标头，以及next，previous，first和last链接关系类型。

在 REST 中，可发现性是一个横切关注点，不仅适用于特定操作，还适用于操作类型。例如，每次创建资源时，客户端应该可以发现该资源的 URI。由于此要求与 ANY Resource 的创建有关，因此我们将单独处理它。

正如我们在上一篇文章中讨论的那样，我们将使用事件来解耦这些关注点，重点是 REST 服务的可发现性。在分页的情况下，事件PaginatedResultsRetrievedEvent在控制器层中触发。然后，我们将使用此事件的自定义侦听器实现可发现性。

简而言之，监听器将检查导航是否允许next，previous，first和last。如果是这样，它会将相关的 URI 作为“链接”HTTP Header 添加到响应中。

现在让我们一步一步来。从控制器传递的UriComponentsBuilder仅包含基本 URL（主机、端口和上下文路径）。因此，我们必须添加其余部分：

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。让我们看看我们如何处理到next的链接：

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());

5. 分页测试

分页和可发现性的主要逻辑都包含在小型、集中的集成测试中。与上一篇文章一样，我们将使用 REST-assured 库来使用 REST 服务并验证结果。

@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());
}

6. 测试分页可发现性

测试客户是否可以发现分页相对简单，尽管有很多内容需要覆盖。 **测试将关注当前页面在导航中的位置，**以及应该从每个位置发现的不同 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);
}

7. 获取所有资源

在分页和可发现性的同一主题上，必须做出选择，是允许客户端一次检索系统中的所有资源，还是客户端必须分页请求它们。如果确定客户端无法通过单个请求检索所有资源，并且需要分页，那么有几个选项可用于响应以获取请求。一种选择是返回 404 ( Not Found ) 并使用Link标头使第一页可发现：

Link=http://localhost:8080/rest/api/admin/foo?page=0&size=2 ; rel=”first”, http://localhost:8080/rest/api/admin/foo?page=103&size=2 ; rel=”last”

另一种选择是将重定向 303（其他）返回到第一页。更保守的方法是简单地为 GET 请求返回 405（不允许的方法）给客户端。

8. 带有RangeHTTP 标头的 REST 分页

实现分页的一种相对不同的方式是使用HTTP Range标头、 Range、Content-Range、If-Range、Accept-Ranges和HTTP 状态代码、 206（部分内容）、413（请求实体太大）和416（请求的范围不可满足）。

这种方法的一种观点是，HTTP Range 扩展不用于分页，它们应该由服务器管理，而不是由应用程序管理。基于 HTTP Range 标头扩展实现分页在技术上是可行的，尽管不像本文中讨论的实现那样普遍。

9. Spring Data REST 分页

在 Spring Data 中，如果我们需要从完整的数据集中返回一些结果，我们可以使用任何Pageable存储库方法，因为它总是返回一个Page。将根据页码、页面大小和排序方向返回结果。 **Spring Data REST 自动识别page, size, sort等URL 参数。** 要使用任何存储库的分页方法，我们需要扩展PagingAndSortingRepository：

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

如果我们调用 http://localhost:8080/subjects， Spring 会自动通过 API添加page, size, sort参数建议：

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

默认情况下，页面大小为 20，但我们可以通过调用类似http://localhost:8080/subjects?page=10 的方法来更改它。

如果我们想在我们自己的自定义存储库 API 中实现分页，我们需要传递一个额外的Pageable参数并确保 API 返回一个Page：

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

每当我们添加自定义 API 时，都会将*/search*端点添加到生成的链接中。因此，如果我们调用 http://localhost:8080/subjects/search ，我们将看到一个支持分页的端点：

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

所有实现 PagingAndSortingRepository的 API都会返回一个Page。如果我们需要从Page返回结果列表，Page的getContent() API提供了作为 Spring Data REST API 结果获取的记录列表。

10. 将List转换为Page

假设我们有一个Pageable对象作为输入，但是我们需要检索的信息包含在一个列表而不是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作为有效结果返回。请注意，如果我们还想支持排序，我们需要在子列表之前对列表进行排序。