Web アプリケーションで
spring_boot_starter_web もアプリケーションの依存関係にある場合、ジェネレーターは 2 つのスターターの間をつなぐものを追加します。コントローラーのメソッドの Pageable や Sort のパラメーターは ?page=&size=&sort= から埋められ、返された Page は Spring Data の安定した JSON として書かれ、よくあるデータの例外は 500 ではなく 409、404、400 で応答されます。スターターは互いに依存せず、ジェネレーターがそれらをつなぎます。
使う理由
一覧のエンドポイントは、クエリからページ、サイズ、順序を読み、サイズに上限を設け、ソートのプロパティをチェックし、合計とともにページを書きます。保存時の衝突は 409、ない行は 404 です。これはどの API でも同じなので、Spring Data Web のルールと Spring Boot のプロパティ名で、一度だけ行われます。
例
@RestController()
@RequestMapping('/api/books')
class BookController {
BookController(this.books);
final BookRepository books;
// GET /api/books?page=1&size=10&sort=year,desc&sort=title
@GetMapping()
Future<Page<Book>> list(@PageableDefault(size: 20, sort: ['title']) Pageable pageable) =>
books.findAllPaged(pageable);
// GET /api/books/search?sort=title,asc
@GetMapping('/search')
Future<List<Book>> search(@RequestParam() String q, @SortDefault(sort: ['year'], direction: Direction.desc) Sort sort) =>
books.findByTitleContaining(q, sort);
}
{
"content": [{"id": 3, "title": "Dune", "year": 1965}],
"page": {"size": 10, "number": 1, "totalElements": 11, "totalPages": 2}
}
Pageable と Sort のパラメーター
pagingArgumentResolvers の Bean (WebMvcConfigurer) がそれらを埋めます。
| リクエスト | 意味 |
|---|---|
page=2 |
ページ番号。0 から (one-indexed-parameters なら 1 から)。 |
size=50 |
ページサイズ。 |
sort=title |
title の昇順。 |
sort=year,desc&sort=title |
year の降順、次に title。 |
max-page-size(2000) を超えるサイズはそれに切り詰められます。1 未満のサイズ、またはないサイズはデフォルト (20) です。- 負または数値でないページは 0 です。
- エンティティにないソートのプロパティは 400 です。
- パラメーターに
@Qualifier('x')を付けると、x_page、x_size、x_sortを読みます。一つのリクエストで 2 つの pageable を使う場合のためです。
| アノテーション | 属性 |
|---|---|
@PageableDefault |
size (10)、page (0)、sort ([])、direction (Direction.asc): リクエストに何もないときのデフォルト。 |
@SortDefault |
sort ([])、direction (Direction.asc)。 |
プロパティ
| キー | デフォルト | 意味 |
|---|---|---|
spring.data.web.pageable.default-page-size |
20 |
リクエストに size がないときのページサイズ。 |
spring.data.web.pageable.max-page-size |
2000 |
最大のページサイズ。より大きい size はこれに切り詰められる。 |
spring.data.web.pageable.one-indexed-parameters |
false |
page を 0 ではなく 1 から始めるかどうか。 |
spring.data.web.pageable.page-parameter |
page |
ページのパラメーターの名前。 |
spring.data.web.pageable.size-parameter |
size |
サイズのパラメーターの名前。 |
spring.data.web.pageable.prefix |
'' |
ページとサイズのパラメーター名の前のプレフィックス。 |
spring.data.web.pageable.qualifier-delimiter |
_ |
@Qualifier とパラメーター名の間 (x_page)。 |
spring.data.web.sort.sort-parameter |
sort |
ソートのパラメーターの名前。 |
公開 API では max-page-size を下げてください。size=2000 を送るクライアントは、それでも 2000 行を読み込みます。
Page の JSON
返された Page<T> は、Spring Data 3.3 の安定した JSON として書かれます。content と、size、number、totalElements、totalPages を持つ page です。Page の実装が変わっても JSON は変わりません。
データの例外への応答
dataAccessExceptionResolver の Bean (HandlerExceptionResolver) は、詳細が固定で、例外のメッセージを決して示さない ProblemDetail で応答します。
| 例外 | ステータス | 詳細 |
|---|---|---|
OptimisticLockingFailureException |
409 | The resource was changed by someone else |
DuplicateKeyException |
409 | The resource already exists |
EmptyResultDataAccessException |
404 | Not found |
PermissionDeniedDataAccessException |
403 | Access denied |
PropertyReferenceException |
400 | Invalid sort property |
InvalidPagingRequestException |
400 | Invalid page or sort request |
InvalidDataArgumentException |
400 | Invalid request value |
InvalidDataArgumentException は呼び出し元の値 (NUL 文字を含むテキスト、文がバインドできるより長いリスト、データベースが拒否する LIKE のパターン) で、開発者の誤りではないため、その他の InvalidDataAccessApiUsageException は 500 のままです。Web スターターはこれらの応答を debug でログに出します。
利用者に残るルール
- リクエストボディはエンティティではなく DTO にバインドしてください。 エンティティにバインドすると、クライアントが ID とバージョンを選べてしまいます。
- 一部のプロパティをソート可能にすべきでない場合は、ソートのプロパティを許可リストにしてください。 ソートは
ORDER BYのオラクルで、クライアントは、パスワードのハッシュのように、読めない値の順序を知ることができます。 - リポジトリに届くテキストを検証してください (
@Pattern、NUL なし)。そうすれば、不正な値はデータ層からではなく、バリデーションによる 400 になります。
Spring (Java) との対応
@GetMapping
Page<Book> list(@PageableDefault(size = 20, sort = "title") Pageable pageable) {
return books.findAll(pageable);
}
パラメーター、アノテーション、プロパティは Spring Data Web と Spring Boot のものです。Spring には、データの例外を 409 や 404 に対応させるデフォルトのマッピングがありません。@ControllerAdvice を書きます。