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 方法中注入两个查询参数： 大小 和 页面 。
或者，我们可以使用 Pageable 对象，它自动映射 page 、 size 和 sort 参数。 此外， PagingAndSortingRepository 实体提供了开箱即用的方法，也支持使用 Pageable 作为参数。
我们还注入了 Http Response 和 UriComponentsBuilder 以帮助实现可发现性——我们通过自定义事件将其解耦。如果这不是 API 的目标，您只需删除自定义事件即可。
最后 - 请注意，本文的重点只是 REST 和 Web 层 - 要深入了解分页的数据访问部分，您可以查看这篇有关 Spring Data 分页的文章。
4. REST 分页的可发现性
在分页范围内，满足 REST 的 HATEOAS 约束 意味着使 API 的客户端能够基于导航中的当前页面发现 下一页 和 上一页 。为此， 我们将使用 Link HTTP 标头，以及“ next ”、“ prev ”、“ first ”和“ last ”链接关系类型 。
在 REST 中， 可发现性是一个横切关注点 ，不仅适用于特定操作，而且适用于操作类型。例如，每次创建资源时，客户端都应该可以发现该资源的 URI。由于此要求与任何资源的创建相关，因此我们将单独处理它。
正如我们在上一篇重点关注 REST 服务的可发现性的文章中所讨论的那样，我们将使用事件来解耦这些问题。在分页的情况下，事件 – PaginatedResultsRetrievedEvent – 在控制器层中触发。然后我们将使用此事件的自定义侦听器实现可发现性。
简而言之，侦听器将检查导航是否允许 下一页 、 上一页 、 第一 页和 最后 一页。如果是，它会将 相关 URI 作为“链接”HTTP 标头添加到响应中 。
现在让我们一步一步来。从控制器传递的 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。让我们看看如何继续处理 下一页 的链接：
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 服务并验证结果。
这些是分页集成测试的一些示例；如需完整的测试套件，请查看 GitHub 项目（链接位于文章末尾）：
@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);
}
请注意， extractURIByRel 的完整低级代码（负责通过 rel 关系提取 URI）位于此处。
7. 获取所有资源
在分页和可发现性的同一主题上， 必须做出选择是允许客户端一次检索系统中的所有资源，还是客户端必须要求对它们进行分页 。
如果选择客户端无法通过单个请求检索所有资源，并且分页不是可选的而是必需的，则可以使用多个选项来响应“获取所有”请求。一个选项是返回 404（ 未找到 ）并使用 链接 标头使第一页可发现：
链接= 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 =“最后”
另一种选择是将重定向 – 303 （参见其他 ） – 返回到首页。更保守的路线是简单地向客户端返回 GET 请求的 405（ 方法不允许） 。
8. 使用 范围 HTTP 标头的 REST 分页
实现分页的一种相对不同的方法是使用 HTTP Range 标头 – Range 、 Content-Range 、 If-Range 、 Accept-Ranges – 和 HTTP 状态代码 – 206（ 部分内容 ）、413（ 请求实体太大 ）、416 （ 请求的范围无法满足 ）。
关于这种方法的一种观点是，HTTP 范围扩展不是用于分页的，它们应该由服务器管理，而不是由应用程序管理。然而，基于 HTTP Range 标头扩展实现分页在技术上是可行的，尽管不像本文中讨论的实现那么常见。
9.Spring Data REST 分页
在 Spring Data 中，如果我们需要从完整的数据集中返回一些结果，我们可以使用任何 Pageable 存储库方法，因为它总是返回一个 Page。 将根据页码、页面大小和排序方向返回结果。
Spring Data REST自动识别 URL 参数，如 页面、大小、排序 等。
要使用任何存储库的分页方法，我们需要扩展 PagingAndSortingRepository：
public interface SubjectRepository extends PagingAndSortingRepository<Subject, Long>{}
如果我们调用 http://localhost:8080/subjects Spring 会自动使用 API 添加 页面、大小、排序 参数建议：
"_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 结果获取的记录列表。
本节中的代码可在spring-data-rest项目中找到。
10. 将 列表 转换为 页面
假设我们有一个 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());
就是这样！我们可以立即返回 页面 作为有效结果。
请注意，如果我们还想支持排序，则需要 在子列表之前对列表进行排序 。
11. 结论
本文说明了如何使用 Spring 在 REST API 中实现分页，并讨论了如何设置和测试可发现性。
如果您想深入了解持久性级别的分页，请查看我的JPA或Hibernate分页教程。
所有这些示例和代码片段的实现都可以在GitHub 项目中找到 - 这是一个基于 Maven 的项目，因此应该很容易导入和运行。