
# 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 のプロパティ名で、一度だけ行われます。

## 例

```dart
@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);
}
```

```json
{
  "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) との対応

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

## 関連項目

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [ページングとソート](paging-and-sorting.md)
- [HandlerExceptionResolver](../spring-boot-starter-web/errors/handler-exception-resolver.md)
