
# Spring との違い

`spring_boot_starter_web` は Spring Boot と Spring MVC に従います。同じアノテーション、意味のある範囲で同じプロパティ名、同じ応答です。このページでは、そうでないすべての箇所とその理由をトピックごとに挙げます。最後のセクションでは、まだないものを挙げます。

## 使う理由

Spring アプリケーションを移植するときや Spring のチュートリアルに沿って進めるときは、どこで動作が期待と異なるかを知っておく必要があります。違いのほとんどは、次の三つの事実から来ています。

- **Dart は Java ではありません。** 実行時のリフレクションも、サーブレットコンテナもありません。例外クラスのアノテーションは実行時に読めず、ある `Type` が別の型のサブタイプかどうかも調べられません。
- **サーバーは Tomcat ではなく `dart:io` の `HttpServer` です。** いくつかの規則はここから来ています。
- **いくつかのデフォルトはより安全です。** Spring がコンテナやアプリケーションに任せている上限のいくつかが、ここには存在します。

## 例

両方で同じコントローラーです。コードはほぼ同じで、違いは以下の詳細にあります。

```dart
@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);
  final BookService books;

  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  @GetMapping()
  Future<List<Book>> search(@RequestParam('q') String? query) => books.search(query);
}
```

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

  @GetMapping
  List<Book> search(@RequestParam(name = "q", required = false) String query) { ... }
}
```

必須か省略可能かは、`required` と `defaultValue` ではなく、Dart のパラメーター (`String?`、デフォルト値) で決まります。[@RequestParam](controllers/request-param.md) を参照してください。

## 設定

- **名前の変わったプロパティ。** `server.servlet.context-path` は `server.context-path`、`server.servlet.session.*` は `server.session.*`、`spring.servlet.multipart.*` は `spring.web.multipart.*` です。サーブレットコンテナがないためです。古いプレフィックスの下のキーは、どのソース (ファイル、コマンドライン、環境変数) にあっても起動を止め、新しいキーを示します。Spring のプロパティマイグレーターは警告をログに出すだけです。
- **このスターター独自のキー** (Spring Boot にはないもの): `server.max-http-request-body-size`、`server.request-timeout`、`server.max-concurrent-requests`、`server.max-connections`、`server.retry-after`、`server.isolates.*`、`spring.web.debug.*`、`server.forward-headers.trusted-proxies`、`server.websocket.*`、`spring.mvc.sse.heartbeat-interval`、`spring.web.multipart.max-part-count` (Spring Boot では `server.tomcat.max-part-count`)、`spring.web.resources.spa-fallback`、`spring.web.resources.directory-index`。
- **`server.connection-timeout`** は Spring Boot 2.0 にあったキーです。Spring Boot 3 と 4 は `server.tomcat.connection-timeout` を使います。
- **`spring.main.register-shutdown-hook` はデフォルトで `false` です** (`spring_boot_dart` のキー)。シグナルを待ち受けると Dart プログラムが終了しなくなるためです。`true` に設定しないと、`Ctrl+C` と SIGTERM はグレースフルシャットダウンなしでプロセスを終了させます。
- **`spring.main.web-application-type`** が知っているのは `none` だけです。サーバーの種類は一つで、`servlet` と `reactive` はありません。
- **`@EnableWebMvc` はありません。** スキャンされたパッケージ内のすべての `@RestController` がマッピングされます。

[すべてのプロパティ](properties.md) を参照してください。

## サーバー

- **Tomcat ではなく `dart:io` の `HttpServer`。** HTTP/1.1 のみで、`server.http2.enabled` は読まれません。`server.tomcat.*` キーはありません。
- **PEM ファイルのパスからの TLS。** キーストアも SSL バンドルも、`classpath:` や `resources:` のロケーションもありません。`server.ssl.client-auth=need` の場合、証明書のないクライアントも TLS ハンドシェイクを完了し、リクエストごとに 403 を受け取ります。[TLS](server/ssl.md) を参照してください。
- **`server.request-timeout` と `RequestDeadline` は拡張です。** Spring がタイムアウトさせるのは接続 (Tomcat) と非同期リクエスト (`spring.mvc.async.request-timeout`) で、同期リクエストの処理ではありません。また、リクエストが行う呼び出しに期限が引き継がれることもありません。[タイムアウト](server/timeouts.md) を参照してください。
- **停滞したリクエストボディ** には `server.connection-timeout` (60 秒) の後に 408 が返ります。Tomcat では読み込みが失敗し、Spring は 400 を返します。
- **設定しない限り、接続数の上限はありません。** `server.max-connections` と `server.max-concurrent-requests` が上限を設定します (Tomcat の `max-connections` はデフォルトで 8192)。どちらかを超えると、リクエストは待たされるのではなく、ただちに `Retry-After` 付きの 503 で応答されます。[過負荷](server/overload.md) を参照してください。
- **スレッドではなく isolate。** Tomcat のワーカースレッドは Bean を共有します。ここではサーバーは一つの isolate から応答します。`server.isolates.count` は isolate を追加し、それぞれが自分の Bean でアプリケーション全体を実行するので、メモリー上のセッション、キャッシュ、カウンターは isolate ごとになります。[isolate のプール](server/isolates.md) を参照してください。
- **`server.max-http-request-body-size` (10 MB) を超えるボディ** は、型にかかわらず 413 になります。Tomcat にはすべてのボディに対するこのような上限はありません。
- **二つの `Host` ヘッダーと、16 進数 2 桁が続かない `%` は受け入れられます** (`dart:io` は最後の `Host` を残し、`/a%G1` は `/a%25G1` として読まれます)。Tomcat はこれらに 400 を返します。
- **リクエストターゲット中の生の `\` は `/` になります。** `dart:io` はサーバーが見る前にターゲットを解析し、生の形を残さないため、`/files/..\..\secret` は `/secret` として届き (`..` は解決済み)、ASCII を超える生のバイトは Latin-1 として読まれます (UTF-8 で送られた `/café` は `/caf%C3%83%C2%A9` として届きます)。Tomcat はどちらにも 400 を返します。フィルター、セキュリティルール、コントローラーはすべて同じパスを見ますが、パスを見るルールを持つ前段のプロキシは、自分で `\` を拒否する必要があります。
- **`Transfer-Encoding` を伴う `Content-Length`** は、サーバーが両方のヘッダーを見たときだけ 400 で応答され、接続が閉じられます (Tomcat は常に 400 を返します)。`dart:io` が両方を見せるのは一部の書き方だけです (長さが先にあり、エンコーディングが正確に `chunked` と書かれていない場合)。それ以外では `dart:io` 自身が `Content-Length` を捨て、リクエストは chunked として読まれます。このようなリクエストを拒否するプロキシを使ってください。
- **`Server` ヘッダーも、デフォルトの `Content-Type` もありません。** `dart:io` の `X-Frame-Options: SAMEORIGIN` と `X-Content-Type-Options: nosniff` がすべての応答に付きます (Spring Security のない Spring Boot はどちらも送りません)。
- **グレースフルシャットダウン** は、どちらのモードでも、開いているイベントストリームと WebSocket セッションを即座に閉じます (1001)。[シャットダウン](server/shutdown.md) を参照してください。
- **Flutter アプリはデフォルトで `127.0.0.1` で待ち受けます。** [組み込みサーバー](server/index.md) を参照してください。

## プロキシの背後で

- **`native` と `framework` は同じことをします。** どちらも、Tomcat の `RemoteIpValve` と同様に、信頼されたプロキシの転送ヘッダーだけを適用します。Spring の `ForwardedHeaderFilter` (`framework`) はすべての相手を信じます。
- **信頼されたプロキシはアドレスと CIDR 範囲です** (`server.forward-headers.trusted-proxies`)。Tomcat の正規表現ではありません。
- **`X-Forwarded-Prefix` と `X-Forwarded-Ssl` は読まれません。**

[リバースプロキシの背後で](server/reverse-proxy.md) を参照してください。

## コントローラーとパラメーター

- **Spring より多くの起動時のチェック**: パラメーターのないパス変数、何も埋められないパラメーター、無効な `@ExceptionHandler` は、問題の一覧とともに起動を止めます。[起動時のチェック](controllers/startup-checks.md) を参照してください。
- **必須か省略可能かは Dart のパラメーターで決まります**。`required` と `defaultValue` ではありません。null 許容のパラメーターは `null` を受け取り、省略可能なパラメーターは Dart のデフォルト値を保ちます。
- **`@ModelAttribute` も、フォームのオブジェクトへのバインドもありません。** フォームのフィールドは、`@RequestParam` (一つのフィールド、リスト、またはすべてを `Map` として) か `@RequestBody() Map<String, String>` でハンドラーに届きます。
- **`HttpSession` パラメーターはありません。** ハンドラーは `request.getSession()` でセッションを取得します。[セッション](sessions.md) を参照してください。
- **独自の引数リゾルバーは組み込みのものより先に問い合わされます** (Spring では後)。そのため、セキュリティスターターの `@AuthenticationPrincipal` のように、スターターがどのパラメーターでも引き受けられます。[WebMvcConfigurer](web-mvc-configurer.md) を参照してください。
- **`@ResponseStatus` はハンドラーメソッドかコントローラークラスに付けます**。例外クラスには付けません。そのアノテーションは実行時に読めないためです。代わりに `ResponseStatusException` を投げるか、`ErrorResponse` を実装してください。

## エラー

- **エラーは常に `ProblemDetail` です** (`application/problem+json`)。Spring Boot のデフォルトは、`spring.mvc.problemdetails.enabled=true` でない限り `/error` の JSON (`timestamp`、`status`、`error`、`path`) です。ここには `/error` エンドポイントも `ErrorController` もなく、`server.error.*` は読まれません。例外は Spring もプレーンテキストで返すもの、つまり拒否された CORS リクエストと WebSocket ハンドシェイクです。
- **`@ExceptionHandler([types])` は実行時の型と完全に一致するものに適用されます**。Dart では `Type` が別の型のサブタイプかどうかを調べられないためです。サブタイプは例外パラメーターの型で一致させます: `@ExceptionHandler() void on(StateError e)`。[@ExceptionHandler](errors/exception-handler.md) を参照してください。
- **`@ControllerAdvice.of(basePackages: ...)` は Java のパッケージの代わりにライブラリ URI のプレフィックス** (`package:shop/admin/`) を受け取り、`annotations` はコントローラーのアノテーションを型の完全一致で照合します。`basePackageClasses` はありません。[@ControllerAdvice](errors/controller-advice.md) を参照してください。
- **`HandlerExceptionResolver` は `ErrorResponse` (または `null`) を返します**。レスポンスに書き込んで `ModelAndView` を返すのではありません。組み込みの解決 (`@ExceptionHandler` メソッド、`ResponseStatusException`) が先に行われ、リゾルバー Bean はその後に問い合わされます。[HandlerExceptionResolver](errors/handler-exception-resolver.md) を参照してください。

## ストリーム、アップロード、ダウンロード

- **宣言された `Stream<Uint8List>` または `Stream<List<int>>` の戻り値は生のバイトです。** Spring MVC にはバイトストリームの戻り値はありません。Spring WebFlux は `Flux<DataBuffer>` を同じように書きます。その他のストリームはサーバー送信イベント (または NDJSON) です。[ダウンロード](streaming/downloads.md) を参照してください。
- **イベントストリームは `:` のコメント行で始まります**。`dart:io` はヘッダーを最初のボディのバイトと一緒に送るためです。クライアントはこれを無視します。[サーバー送信イベント](streaming/sse.md) を参照してください。
- **タイムアウトのない `SseEmitter` は、`spring.mvc.async.request-timeout` が設定されていなければタイムアウトしません**。デフォルトが適用されるサーブレットコンテナ (Spring では Tomcat の 30 秒) がないためです。完了したとき、クライアントが去ったとき、サーバーが停止したときに終わります。`spring.mvc.async.request-timeout` は `SseEmitter` にだけ適用されます。
- **サーブレットコンテナのないマルチパート。** `spring.web.multipart.*` キーは、Spring Boot の `spring.servlet.multipart.*` からサーブレットを除いたもので、一時ファイルはこのスターター独自のものです。`file-size-threshold` は `0B` なので、すべてのファイルがディスクに書かれます。`@RequestPart` にバインドされるのは `multipart/form-data` のパートだけで、`multipart/mixed` はバインドされません。[アップロード](streaming/uploads.md) を参照してください。
- **バイト範囲はリクエストごとに一つ。** 複数の範囲を指定すると、`multipart/byteranges` ではなくコンテンツ全体が返ります。コントローラーが返す `Resource` には `ETag` がありません (静的リソースにはあります)。

## 静的リソース

Spring の `ResourceHttpRequestHandler` より厳しく、少し機能が多くなっています。[静的リソース](static-resources.md) を参照してください。

- **ドットファイルは提供されません** (Spring は提供します)。`.well-known/` は提供されます。
- **パス中の `;` と空のセグメントは 404 になります。** Spring Security のファイアウォールはこれらに 400 を返し、素の Spring MVC は提供します。
- **ロケーションの外に出るシンボリックリンクは拒否されます**。Windows だけが別のファイルとして読むパスも同様です。
- **弱い `ETag` を送ります** (Spring は `etagGenerator` が設定されていない限り送りません)。また、`X-Content-Type-Options: nosniff` (Spring では Spring Security が追加します)、`304` にも `Cache-Control`、そして `apple-app-site-association` に `application/json` を送ります。
- **ファイルのないパス** にはディスパッチャーの 404 (`No endpoint GET /x.`) が返ります。Spring 6.1 は `No static resource x.` を返します。
- **`HandlerInterceptor` はこれらには実行されません**。コントローラーメソッドのためのものです。
- **`spring.web.resources.spa-fallback` と `directory-index`** はこのスターター独自のキーです。
- **サポートされないもの:** `spring.web.resources.chain.enabled`、`chain.cache`、バージョン戦略、webjars のマッピング。
- **事前圧縮されたバリアント** は、Spring の `resourceChain(true).addResolver(new EncodedResourceResolver())` の代わりに、`ResourceHandlerRegistration` の設定 (`setCompressed`、または `spring.web.resources.chain.compressed`) です。
- **ロケーションは `resources:` と `file:` です。** `resources:` は `lib/resources/` のフォルダーで、そのルート (設定を置く場所) ではありません。その他のプレフィックスは起動を止めます。Dart には jar がないので、`META-INF/resources/` と `resources/` はデフォルトに含まれません。

## セッション

- **セッション Cookie はデフォルトで `SameSite=Lax` です。**
- **セッション数には上限があります** (`server.session.max-sessions`、10000)。上限に達すると期限切れのセッションが削除され、それでも足りなければ新しいセッションは 503 で拒否されます。
- **セッションは一つのプロセスのメモリーに置かれます**。別の `HttpSessionRepository` Bean を宣言した場合を除きます。

[セッション](sessions.md) を参照してください。

## CORS

- **複数のハンドラーに一致するプリフライト** (それぞれに `@CrossOrigin` があり、そのパスに完全に一致するハンドラーがないか、複数ある場合) は、最初のハンドラーの CORS ルールを受け取ります。Spring は、ハンドラーの具体性にかかわらず、任意のオリジンから資格情報付きで許可します。
- **表示可能な US-ASCII 以外の CORS の値は 403 で拒否されます**: 空白、制御文字、ASCII を超える文字を含む `Origin`、またはプリフライトで要求されたメソッドやヘッダーは、`*` が任意を許可する場合でも拒否されます。Spring はそのようなメソッドやヘッダーをそのまま返し (ブラウザーはそれを送りません)、そのような `Origin` も拒否します。
- **1024 文字を超える `Origin` は決して許可されません** (CORS と WebSocket ハンドシェイク: 403)。ルールにかかわらず、`*` も含みます。実際のオリジンは 300 文字未満です。Spring はどの長さでもチェックし、そのパターンの正規表現は長さに応じて遅くなります。
- **`spring.web.cors.*` は読まれません。** CORS は `@CrossOrigin`、`WebMvcConfigurer.addCorsMappings`、または `corsConfigurationSource` Bean で設定します。

[CORS](cors.md) を参照してください。

## WebSocket

- **メッセージの上限はこのスターターのプロパティです** (`server.websocket.max-text-message-size` と `max-binary-message-size`、それぞれ 8 KB で、Tomcat のデフォルト)。Spring はこれらをコンテナ (`ServletServerContainerFactoryBean`) に設定します。テキストの上限は UTF-8 のバイト数で数えます。Tomcat は文字数で数えます。
- **permessage-deflate はありません。** Tomcat はこれをネゴシエートします。
- **すべてのセッションに送信の上限があります** (`server.websocket.send-buffer-size-limit` が 512 KB、`send-time-limit` が 10 秒。超えると接続は 4500 で切断されます)。これは Spring の `ConcurrentWebSocketSessionDecorator` のデフォルトです。Spring ではこれらは STOMP セッションと、デコレートしたセッションに適用されます。Tomcat 上の素のハンドラーは、代わりに送信スレッドをブロックします (Tomcat の 20 秒のブロッキング送信タイムアウトまで)。同じように待つには、`sendMessage` の後に `IoWebSocketSession.flush()` を await してください。

[WebSocket](server/websocket.md) を参照してください。

## テスト

- **`MockMvc` は名前付きの期待値を受け取ります** (`andExpect(status: 200, json: ...)`、マッチャーも使えます)。`status().isOk()` と `jsonPath(...)` の代わりです。
- **`ApplicationContextRunner` はサーバーを起動しません**。テストが `spring.test.web-environment=random-port` を設定した場合を除きます。

[テスト](testing.md) を参照してください。

## まだないもの

以下は計画されていますが、まだありません。

- **`@ConditionalOnWebApplication`** と、**`@WebMvcTest`** のようなテストスライス。
- **`ResponseBodyEmitter`。** `Stream<T>` の戻り値がサーバー送信イベントと NDJSON をカバーします。
- `multipart/byteranges` としての**複数のバイト範囲**、コントローラーが返す **`Resource` の `ETag`**、そして **`multipart/mixed` での `@RequestPart`**。
- **`spring.web.cors.*`** と **`server.max-http-request-header-size`**。
- **ルートごとのリクエストタイムアウト。** `server.request-timeout` はすべてのリクエストに適用されます。
- **Flutter:** ハンドラーがメインのアイソレートをブロックしたときの警告、大きな JSON ボディの別のアイソレートでのデコード、そしてバックグラウンドのアイソレートでのサーバー全体の実行。
- 同じ `WebServerFactory` の背後にある**その他のサーバー** (たとえば `shelf` 上のもの)、そして WebSocket 上の **STOMP**。

## Spring (Java) との対応

このページ全体が Spring との比較です。要するに、コードは小さな変更で移行できます。

- アノテーションは名前を保ちます (`@RestController`、`@GetMapping`、`@PathVariable`、`@RequestBody`、`@ExceptionHandler`、`@ControllerAdvice`、`@CrossOrigin`)。
- `required = false` は null 許容のパラメーターに、`defaultValue` は Dart のデフォルト値になります。
- `server.servlet.*` と `spring.servlet.multipart.*` から `servlet` がなくなります。
- エラーのボディは `ProblemDetail` です。
- 例外クラスの `@ResponseStatus` は `ResponseStatusException` か `ErrorResponse` になります。

## 関連項目

- [概要](index.md)
- [すべてのプロパティ](properties.md)
- [組み込みサーバー](server/index.md)
- [コントローラー](controllers/index.md)
- [エラー](errors/index.md)
- [静的リソース](static-resources.md)
- [テスト](testing.md)
