ページングとソート

このセクションでは、Spring Data REST による Spring Data リポジトリのページングとソートの抽象化の使用について説明します。これらの機能を理解するには、使用するリポジトリ実装 (Spring Data JPA など) の Spring Data ドキュメントを参照してください。

ページング

Spring Data REST は、大きな結果セットからすべてを返すのではなく、ページサイズと開始ページ番号に影響を与えるいくつかの URL パラメーターを認識します。

PagingAndSortingRepository<T, ID> を継承してすべてのエンティティのリストにアクセスすると、最初の 20 個のエンティティへのリンクが表示されます。ページサイズを他の数値に設定するには、次のように size パラメーターを追加します。

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

上記の例では、ページサイズを 5 に設定しています。

独自のクエリメソッドでページングを使用するには、追加の Pageable パラメーターを受け入れ、List ではなく Page または Slice を返すようにメソッドシグネチャーを変更する必要があります。例: 次のクエリメソッドは /people/search/nameStartsWith にエクスポートされ、ページングをサポートします。

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

Spring Data REST エクスポーターは、返された Page/Slice を認識し、非ページレスポンスの場合と同様に、レスポンスの本文で結果を返しますが、データの前と次のページを表す追加のリンクがリソースに追加されます。

前と次のリンク

ページングされた各レスポンスは、IANA 定義のリンク関係 prev [W3C] (英語) および next [W3C] (英語) を使用して、現在のページに基づいて結果の前のページと次のページへのリンクを返します。ただし、現在結果の最初のページを表示している場合、prev リンクはレンダリングされません。結果の最後のページでは、next リンクはレンダリングされません。

次の例を考えてみましょう。ここでは、ページサイズを 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 が表示されます。

1	`self` リンクは、いくつかのオプションを備えたコレクション全体を提供します。
2	`next` リンクは、同じページサイズを想定して、次のページを指します。
3	下部には、ページのサイズ、合計要素、合計ページ、現在表示しているページ番号など、ページ設定に関する追加データがあります。

コマンドラインで curl などのツールを使用する場合、ステートメントにアンパサンド（&）が含まれていると、URI 全体を引用符で囲む必要があります。

self および next URI は、実際には URI テンプレートであることに注意してください。size だけでなく、page と sort もオプションのフラグとして受け入れます。

前述のように、HAL ドキュメントの下部には、ページに関する詳細のコレクションが含まれています。この追加情報により、ユーザーがデータを表示するときの全体的な位置を反映するように、スライダーやインジケーターなどの UI ツールを簡単に構成できます。例: 前の例のドキュメントは、最初のページ（ページ番号は 0 から始まります）を見ていることを示しています。

次の例は、next リンクをたどるとどうなるかを示しています。

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

これは、次の違いを除いて、非常によく似ています。

1	`next` リンクはさらに別のページを指し、`self` リンクに対する相対的な視点を示します。
2	`prev` リンクが表示され、前のページへのパスが示されます。
3	現在の番号は 1 です（2 ページ目を示します）。

この機能を使用すると、画面上のオプションのボタンをこれらのハイパーメディアコントロールにマップでき、URI をハードコードしなくても UI エクスペリエンスのナビゲーション機能を実装できます。実際、ユーザーはページサイズのリストから選択して、提供されるコンテンツを動的に変更することができます。上部または下部の next および `prev コントロールを書き直す必要はありません。

ソート

Spring Data REST は、リポジトリの並べ替えサポートを使用する並べ替えパラメーターを認識します。

特定のプロパティで結果を並べ替えるには、結果を並べ替えるプロパティの名前を使用して sort URL パラメーターを追加します。プロパティ名にコンマ（,）を追加し、さらに asc または desc を追加することで、並べ替えの方向を制御できます。以下では、文字 "K" で始まる名前を持つすべての Person エンティティに対して PersonRepository で定義された findByNameStartsWith クエリメソッドを使用し、name プロパティの結果を降順で並べ替える並べ替えデータを追加します。

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

結果を複数のプロパティで並べ替えるには、必要な数の sort=PROPERTY パラメーターを追加し続けます。それらは、クエリ文字列に表示される順序で Pageable に追加されます。結果は、トップレベルのネストされたプロパティで並べ替えることができます。プロパティパス表記を使用して、ネストされた並べ替えプロパティを表現します。リンク可能な関連付け（つまり、最上位のリソースへのリンク）による並べ替えはサポートされていません。