本文将重点介绍如何使用 Spring MVC 和 Spring Data 在 RESTful API 中实现分页。
在分页范围内,满足 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 中,如果我们需要从完整的结果集中返回一些结果,则可以使用任何 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 中,而不是一个 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