分頁與排序

本節說明 Spring Data REST 如何使用 Spring Data Repository 的分頁和排序抽象概念。若要熟悉這些功能，請參閱您使用的儲存庫實作 (例如 Spring Data JPA) 的 Spring Data 文件。

分頁

Spring Data REST 辨識一些 URL 參數，這些參數會影響頁面大小和起始頁碼，而不是從大型結果集中傳回所有內容。

如果您擴充 PagingAndSortingRepository<T, ID> 並存取所有實體的清單，您會取得前 20 個實體的連結。若要將頁面大小設定為任何其他數字，請新增 size 參數，如下所示

https://127.0.0.1:8080/people/?size=5

上述範例將頁面大小設定為 5。

若要在您自己的查詢方法中使用分頁，您需要變更方法簽名以接受額外的 Pageable 參數，並傳回 Page 或 Slice 而不是 List。例如，以下查詢方法會匯出至 /people/search/nameStartsWith 並支援分頁

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

Spring Data REST 匯出器會辨識傳回的 Page/Slice，並在回應主體中提供結果，就像非分頁回應一樣，但資源中會新增其他連結以表示資料的前一頁和下一頁。

每個分頁回應都會根據目前頁面，使用 IANA 定義的連結關係 prev 和 next，傳回結果的前一頁和下一頁連結。但是，如果您目前位於結果的第一頁，則不會呈現 prev 連結。對於結果的最後一頁，則不會呈現 next 連結。

請考慮以下範例，我們將頁面大小設定為 5

curl localhost:8080/people?size=5
{
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/persons{&sort,page,size}", (1)
      "templated" : true
    },
    "next" : {
      "href" : "https://127.0.0.1:8080/persons?page=1&size=5{&sort}", (2)
      "templated" : true
    }
  },
  "_embedded" : {
  	… data …
  },
  "page" : { (3)
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 0
  }
}

在頂端，我們看到 _links

1 self 連結提供包含一些選項的完整集合。
2 next 連結指向下一頁，假設頁面大小相同。
3 底部是關於頁面設定的額外資料，包括頁面大小、元素總數、頁面總數以及您目前檢視的頁碼。
當在命令列上使用 curl 等工具時，如果您的陳述式中有 & 符號 (&)，您需要將整個 URI 括在引號中。

請注意，self 和 next URI 實際上是 URI 範本。它們不僅接受 size，也接受 page 和 sort 作為選用旗標。

如前所述，HAL 文件的底部包含關於頁面的詳細資訊集合。當使用者檢視資料時，這些額外資訊可讓您輕鬆設定 UI 工具 (例如滑桿或指示器) 以反映使用者的整體位置。例如，上述範例中的文件顯示我們正在檢視第一頁 (頁碼從 0 開始)。

以下範例顯示當我們追蹤 next 連結時會發生什麼事

$ curl "https://127.0.0.1:8080/persons?page=1&size=5"
{
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/persons{&sort,projection,page,size}",
      "templated" : true
    },
    "next" : {
      "href" : "https://127.0.0.1:8080/persons?page=2&size=5{&sort,projection}", (1)
      "templated" : true
    },
    "prev" : {
      "href" : "https://127.0.0.1:8080/persons?page=0&size=5{&sort,projection}", (2)
      "templated" : true
    }
  },
  "_embedded" : {
	... data ...
  },
  "page" : {
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 1 (3)
  }
}

這看起來非常相似，但有以下差異

1 next 連結現在指向另一個頁面，表示其相對於 self 連結的視角。
2 現在出現 prev 連結，為我們提供通往上一頁的路徑。
3 目前的數字現在是 1 (表示第二頁)。

此功能可讓您將螢幕上的選用按鈕對應到這些超媒體控制項，讓您可以為 UI 體驗實作導覽功能，而無需硬式編碼 URI。事實上，使用者可以從頁面大小清單中選取，動態變更提供的內容，而無需重寫頂端或底部的 next 和 `prev 控制項。

排序

Spring Data REST 辨識使用儲存庫排序支援的排序參數。

若要讓您的結果依特定屬性排序，請新增 sort URL 參數，並指定您要排序結果的屬性名稱。您可以透過在屬性名稱後方加上逗號 (,)，再加上 asc 或 desc 來控制排序方向。以下範例會使用在 PersonRepository 上定義的 findByNameStartsWith 查詢方法，針對名稱以字母 “K” 開頭的所有 Person 實體，並新增排序資料，以依 name 屬性以遞減順序排序結果

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

若要依多個屬性排序結果，請根據需要持續新增多個 sort=PROPERTY 參數。它們會依照在查詢字串中出現的順序新增至 Pageable。結果可以依最上層和巢狀屬性排序。使用屬性路徑表示法來表示巢狀排序屬性。不支援依可連結關聯 (即，連結到最上層資源的連結) 排序。