Paging and Sorting

本节记录了 Spring Data REST 如何使用 Spring Data Repository 分页和分类抽象。若要熟悉这些功能，请参阅你使用的存储库实现（例如 Spring Data JPA）的 Spring Data 文档。

This section documents Spring Data REST’s usage of the Spring Data Repository paging and sorting abstractions. To familiarize yourself with those features, see the Spring Data documentation for the repository implementation you use (such as Spring Data JPA).

Paging

Spring Data REST 并非返回大型结果集中的全部内容，而是识别一些影响页面大小和起始页号的 URL 参数。

Rather than return everything from a large result set, Spring Data REST recognizes some URL parameters that influence the page size and the starting page number.

如果你扩展 PagingAndSortingRepository<T, ID> 并访问所有实体的列表，则将获得指向前 20 个实体的链接。要将页面大小设置为任何其他数字，请添加 size 参数，如下所示：

If you extend PagingAndSortingRepository<T, ID> and access the list of all entities, you get links to the first 20 entities. To set the page size to any other number, add a size parameter, as follows:

http://localhost:8080/people/?size=5

前一个示例将页面大小设置为 5。

The preceding example sets the page size to 5.

要在您自己的查询方法中使用分页，您需要更改方法签名以接受附加的 Pageable 参数，并返回 Page 或 Slice 而不是 List。例如，以下查询方法已导出到 /people/search/nameStartsWith 并支持分页：

To use paging in your own query methods, you need to change the method signature to accept an additional Pageable parameter and return a Page or Slice rather than a List. For example, the following query method is exported to /people/search/nameStartsWith and supports paging:

@RestResource(path = "nameStartsWith", rel = "nameStartsWith")
public Page findByNameStartsWith(@Param("name") String name, Pageable p);

Spring Data REST 导出程序会识别返回的 Page/Slice，并将结果作为响应的主体提供，就像处理非分页响应一样，但会向资源添加其他链接以表示上一页和下一页数据。

The Spring Data REST exporter recognizes the returned Page/Slice and gives you the results in the body of the response, just as it would with a non-paged response, but additional links are added to the resource to represent the previous and next pages of data.

每个分页响应都基于当前页，使用 IANA 定义的链接关系 prev 和 next，返回指向结果的前一页和下一页的链接。但是，如果您当前位于结果的第一页，则不会呈现 prev 链接。对于结果的最后一页，不会呈现 next 链接。

Each paged response returns links to the previous and next pages of results based on the current page by using the IANA-defined link relations prev and next. If you are currently at the first page of results, however, no prev link is rendered. For the last page of results, no next link is rendered.

考虑以下示例，其中我们将页面大小设置为 5：

Consider the following example, where we set the page size to 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：

At the top, we see _links:

1 The self link serves up the whole collection with some options.
2 The next link points to the next page, assuming the same page size.
3 At the bottom is extra data about the page settings, including the size of a page, total elements, total pages, and the page number you are currently viewing.

在命令行上使用 curl 等工具时，如果您的语句中包含一个与符号（&），则需要将整个 URI 用引号引起来。

When using tools such as curl on the command line, if you have a ampersand (&) in your statement, you need to wrap the whole URI in quotation marks.

请注意，self 和 next URI 实际上是 URI 模板。它们不仅接受 size，还将 page 和 sort 作为可选标志。

Note that the self and next URIs are, in fact, URI templates. They accept not only size, but also page and sort as optional flags.

如前所述，HAL 文档的底部包括有关页面的详细信息集合。这些额外信息使您可以轻松配置像滑块或指示器这样的 UI 工具，以反应用户在查看数据时的总体位置。例如，前一个示例中的文档显示我们正在查看第一页（页码从 0 开始）。

As mentioned earlier, the bottom of the HAL document includes a collection of details about the page. This extra information makes it easy for you to configure UI tools like sliders or indicators to reflect the user’s overall position when they view the data. For example, the document in the preceding example shows we are looking at the first page (with page numbers starting at 0).

以下示例显示了当我们跟随 next 链接时会发生的情况：

The following example shows What happens when we follow the next link:

$ 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
  }
}

除了以下不同之处，这看起来非常相似：

This looks very similar, except for the following differences:

1 The next link now points to yet another page, indicating its relative perspective to the self link.
2 A prev link now appears, giving us a path to the previous page.
3 The current number is now 1 (indicating the second page).

此功能允许您将屏幕上的可选按钮映射到这些超媒体控件，使您能够针对 UI 体验实现导航功能，而无需对 URI 进行硬编码。事实上，用户可以选择页面大小列表，动态更改提供的内容，而无需重写顶部或底部的 next 和 prev 控件。

This feature lets you map optional buttons on the screen to these hypermedia controls, letting you implement navigational features for the UI experience without having to hard code the URIs. In fact, the user can be empowered to pick from a list of page sizes, dynamically changing the content served, without having to rewrite the next and `prev controls at the top or bottom.

Sorting

Spring Data REST 识别使用存储库排序支持的排序参数。

Spring Data REST recognizes sorting parameters that use the repository sorting support.

若要对特定属性对结果进行排序，请添加带有属性名称的 sort URL 参数，您希望对其排序结果。您可以通过在属性名称后附加逗号（,）加上 asc 或 desc 来控制排序顺序。以下将使用在 PersonRepository 上定义的 findByNameStartsWith 查询方法，针对所有以字母“K”开头的 Person 实体，并添加根据 name 属性降序排列结果的排序数据：

To have your results sorted on a particular property, add a sort URL parameter with the name of the property on which you want to sort the results. You can control the direction of the sort by appending a comma (,) to the the property name plus either asc or desc. The following would use the findByNameStartsWith query method defined on the PersonRepository for all Person entities with names starting with the letter “K” and add sort data that orders the results on the name property in descending order:

curl -v "http://localhost:8080/people/search/nameStartsWith?name=K&sort=name,desc"

要按多个属性对结果进行排序，请根据需要继续添加尽可能多的 sort=PROPERTY 参数。它们会按照在查询字符串中出现的顺序添加到 Pageable 中。可以按顶级和嵌套属性对结果进行排序。使用属性路径表示法来表示嵌套排序属性。不支持按可链接关联（即，指向顶级资源的链接）进行排序。

To sort the results by more than one property, keep adding as many sort=PROPERTY parameters as you need. They are added to the Pageable in the order in which they appear in the query string. Results can be sorted by top-level and nested properties. Use property path notation to express a nested sort property. Sorting by linkable associations (that is, links to top-level resources) is not supported.