
# spring_boot_starter_web

`spring_boot_starter_web` は Spring for Dart の HTTP サーバーで、Spring Boot の `spring-boot-starter-web` と Spring MVC を Dart に移植したものです。`@GetMapping('/books/{isbn}')` のようなアノテーションを付けたメソッドを持つコントローラークラスを書きます。スターターは各リクエストを適切なメソッドに送り、パス、クエリ、ヘッダー、ボディからその引数を埋め、戻り値をレスポンスに変換します。

## 使う理由

REST API では、どのエンドポイントの周りでも同じ作業が必要です。パスを解析し、クエリを読み、JSON をデコードして検証し、エラーを一つの形で返し、JSON を書き戻します。`dart:io` の `HttpServer` の上で手書きすると、このコードはエンドポイントごとに増えていきます。スターターがこれを代わりに行います。

- `spring_core_dart` の `ObjectMapper` による JSON の入出力。
- `@Valid()` によるリクエストボディのバリデーション。
- 標準の `ProblemDetail` ボディ (RFC 9457、`application/problem+json`) としてのエラー。
- `Stream` からのサーバー送信イベントと NDJSON。
- ファイルのアップロード (`multipart/form-data`) と、`Range` に対応したダウンロード。
- ビルド済みの Flutter Web アプリなどの静的ファイルを、キャッシュ用のヘッダー付きで配信。
- フィルター、インターセプター、CORS、セッション。

Dart のバックエンドや、モバイル・デスクトップの Flutter アプリ内のローカルサーバー (ローカル API、コンパニオンサーバー) に使います。サーバーは `dart:io` の `HttpServer` で、差し替え可能なファクトリーの背後にあります。ルーティングのコードはすべてジェネレーターがビルド時に書き出すため、実行時のリフレクションはありません。

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_web: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # 必須: コントローラーを記述する
  spring_boot_starter_test: ^0.9.0     # テスト用の MockMvc と springBootTest
  test: ^1.33.0
```

インポートは一つで足ります。`package:spring_boot_starter_web/spring_boot_starter_web.dart` は `spring_boot_dart`、`spring_web_dart` (アノテーション、`ResponseEntity`、`ProblemDetail`、サーバーのリクエストとレスポンス)、`spring_boot_starter_logging` もエクスポートします。他の Spring Boot スターターと同じく、アプリケーションに必要な依存関係はこれだけです。

## 例

1 ファイルで完結するアプリケーション:

```dart
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

import 'spring_gen/main.spring.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

class NewBook {
  const NewBook({required this.isbn, required this.title});

  @NotBlank()
  @Size(min: 4, max: 13)
  final String isbn;

  @NotBlank()
  final String title;
}

@Service()
class BookService {
  final _books = <String, Book>{
    '978-0': const Book(isbn: '978-0', title: 'Dune'),
  };

  Book? find(String isbn) => _books[isbn];

  Book add(NewBook book) =>
      _books[book.isbn] = Book(isbn: book.isbn, title: book.title);
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  // GET /api/books/978-0 → 200 {"isbn":"978-0","title":"Dune"}
  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) =>
      books.find(isbn) ??
      (throw ResponseStatusException(HttpStatus.notFound, 'No book $isbn'));

  // POST /api/books → Location ヘッダー付きの 201。不正なボディは 400。
  @PostMapping()
  ResponseEntity<Book> create(@RequestBody() @Valid() NewBook book) {
    final added = books.add(book);
    return ResponseEntity.created(Uri.parse('/api/books/${added.isbn}'))
        .body(added);
  }
}

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

```properties
# lib/resources/application.properties
server.port=8080
spring.main.register-shutdown-hook=true
```

`Book` と `NewBook` には JSON のためのアノテーションは不要です。コントローラーが受け取り、返すクラスが同じパッケージにあれば、ジェネレーターはそれぞれをコントローラーでの使われ方に応じて記述します。返されるだけのクラスにはゲッターを、`@RequestBody` のクラスにはコンストラクターとセッターを (`@Valid()` 付きなら制約を持つプロパティのゲッターも) 記述します。JSON として書き出す `Object` など、ビルドから見えない値には、そのクラスに `@Introspected()` が必要です ([JSON](../spring-core-dart/json/index.md) を参照)。

## 実行する

```bash
dart run build_runner build   # bin/spring_gen/main.spring.dart を書き出す
dart run bin/main.dart
```

アノテーションを追加・変更したら `build_runner` を再実行します。コンテキストの準備ができるとサーバーが起動し、ロガー `spring.web.server` で次のログを出力します。

```text
INFO  Web server started on port 8080 (http)
```

続いて:

```bash
curl localhost:8080/api/books/978-0
# {"isbn":"978-0","title":"Dune"}

curl -i localhost:8080/api/books/123
# HTTP/1.1 404 Not Found
# content-type: application/problem+json
# {"type":"about:blank","title":"Not Found","status":404,"detail":"No book 123","instance":"/api/books/123"}
```

起動するもの:

- **有効化するものはありません。** `@EnableWebMvc` はありません。スキャンされたコードのすべての `@RestController` (およびすべての通常の `@Controller`) がマッピングされ、コンテキストの準備ができるとサーバーが起動します。
- **コントローラーが先にチェックされます。** マッピングに誤りがあると、すべての問題の一覧とともに起動が止まります ([起動時のチェック](controllers/startup-checks.md) を参照)。
- **`Ctrl+C` でサーバーがグレースフルに停止する**のは、アプリケーションがシグナルでコンテキストを閉じる場合だけです。`spring.main.register-shutdown-hook=true` を設定してください。シグナルを待ち受けると Dart プログラムが終了しなくなるため、Spring Boot と異なり、ここではデフォルトが `false` です ([シャットダウン](server/shutdown.md) を参照)。
- **ポートが使用中**の場合は、そのポートと変更すべきプロパティを示すレポートとともに起動が失敗します。

## 内容

はじめに:

- [テスト](testing.md): メモリ上の `MockMvc`、または空きポートで動く実際のサーバー。

コントローラー:

- [コントローラー](controllers/index.md): リクエストがメソッドに届くまで。
- [@RestController](controllers/rest-controller.md): リクエストに応答するクラス。
- [@RequestMapping と @GetMapping](controllers/request-mapping.md): パス、メソッド、そして `produces`、`consumes`、`headers` の条件。
- [@PathVariable](controllers/path-variable.md): パスからの値。
- [@RequestParam](controllers/request-param.md): クエリパラメーターとフォームのフィールド。
- [@RequestBody](controllers/request-body.md): `@Valid()` で検証される JSON ボディ。
- [ヘッダー、クッキー、リクエスト](controllers/headers-and-cookies.md): `@RequestHeader`、`@CookieValue`、アノテーションのない引数。
- [戻り値](controllers/results.md): メソッドが返すものと、それがどんなレスポンスになるか。
- [起動時のチェック](controllers/startup-checks.md): アプリケーションの起動時に見つかる誤り。

エラー:

- [エラー](errors/index.md): デフォルトの応答、各エラーのステータス、ログ。
- [ProblemDetail](errors/problem-detail.md): RFC 9457 のエラーボディと、それを持つ例外。
- [@ExceptionHandler](errors/exception-handler.md): 例外を独自の応答に変換します。
- [@ControllerAdvice](errors/controller-advice.md): すべてのコントローラーに対する例外ハンドラー。
- [HandlerExceptionResolver](errors/handler-exception-resolver.md): ライブラリが独自の例外をマッピングする方法。

ストリームとファイル:

- [サーバー送信イベント](streaming/sse.md): `EventStream`、`Stream<T>`、`SseEmitter`。
- [アップロード](streaming/uploads.md): `multipart/form-data`、`@RequestPart`、`MultipartFile`。
- [ダウンロード](streaming/downloads.md): `Range` と `Last-Modified` に対応した `Resource` の戻り値。
- [StreamingResponseBody](streaming/streaming-response-body.md): その場で書き出すボディと、バイトストリーム。

Web の機能:

- [静的リソース](static-resources.md): `lib/resources/static/` やディレクトリのファイル、シングルページアプリ。
- [セッション](sessions.md): `HttpSession`、そのクッキーと制限。
- [フィルター](filters.md): すべてのリクエストを囲む `WebFilter` Bean。
- [WebMvcConfigurer](web-mvc-configurer.md): インターセプター、引数リゾルバー、CORS マッピング、リソースハンドラー。
- [CORS](cors.md): `@CrossOrigin`、グローバルなルール、`corsConfigurationSource` Bean。

サーバー:

- [サーバー](server/index.md): `server.*`、起動と停止、ファクトリー。
- [SSL](server/ssl.md): PEM ファイルによる HTTPS、クライアント証明書。
- [圧縮](server/compression.md): 対応するクライアント向けの gzip。
- [タイムアウト](server/timeouts.md): `server.connection-timeout` と `server.request-timeout`。
- [過負荷](server/overload.md): `server.max-concurrent-requests` と `server.max-connections`。ただちに返される `Retry-After` 付きの 503。
- [isolate のプール](server/isolates.md): `server.isolates.count`、一つのポートを担当する複数の isolate、それによって変わること。
- [isolate のスケーリング](server/scaling.md): `IsolateScaler` と `server.isolates.scaling=auto`。
- [毎秒のリクエスト数](server/qps.md): デバッグ機能 `qps`。
- [リバースプロキシの背後で](server/reverse-proxy.md): `Forwarded` と `X-Forwarded-*` ヘッダー。
- [シャットダウン](server/shutdown.md): グレースフルな停止と即時停止。
- [ハンドラーマッピング](server/handler-mappings.md): ディスパッチャーと独自の `HandlerMapping` Bean。
- [WebSocket](server/websocket.md): 同じポートで動く `spring_boot_starter_websocket` のエンドポイント。

リファレンス:

- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md): Spring Boot と動作が異なる点。

## Spring (Java) との対応

```java
@RestController
@RequestMapping("/api/books")
class BookController {
  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { ... }

  @PostMapping
  ResponseEntity<Book> create(@RequestBody @Valid NewBook book) { ... }
}

@SpringBootApplication
class ShopApplication {
  public static void main(String[] args) {
    SpringApplication.run(ShopApplication.class, args);
  }
}
```

重要な違い:

- ルートはジェネレーターがビルド時に書き出します。アノテーションを変更したら `build_runner` を実行してください。
- `@SpringBootApplication()` はクラスではなく `main` 関数に付けます。
- エラーは常に `ProblemDetail` ボディです。`/error` エンドポイントも `ErrorController` もありません。
- 引数が必須かどうかは、`required` や `defaultValue` 属性ではなく、Dart の引数 (nullable か、デフォルト値があるか) で決まります。
- すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [spring_core_dart](../spring-core-dart/index.md)
- [バリデーション](../spring-core-dart/validation/index.md)
- [JSON](../spring-core-dart/json/index.md)
- [ビルドに含まれるもの](optimizations.md)
