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。
アノテーション 属性
@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 でログに出します。

利用者に残るルール

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 を書きます。

関連項目