Spring との違い
spring_boot_starter_web は Spring Boot と Spring MVC に従います。同じアノテーション、意味のある範囲で同じプロパティ名、同じ応答です。このページでは、そうでないすべての箇所とその理由をトピックごとに挙げます。最後のセクションでは、まだないものを挙げます。
使う理由
Spring アプリケーションを移植するときや Spring のチュートリアルに沿って進めるときは、どこで動作が期待と異なるかを知っておく必要があります。違いのほとんどは、次の三つの事実から来ています。
- Dart は Java ではありません。 実行時のリフレクションも、サーブレットコンテナもありません。例外クラスのアノテーションは実行時に読めず、ある
Typeが別の型のサブタイプかどうかも調べられません。 - サーバーは Tomcat ではなく
dart:ioのHttpServerです。 いくつかの規則はここから来ています。 - いくつかのデフォルトはより安全です。 Spring がコンテナやアプリケーションに任せている上限のいくつかが、ここには存在します。
例
両方で同じコントローラーです。コードはほぼ同じで、違いは以下の詳細にあります。
@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);
}
@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 を参照してください。
設定
- 名前の変わったプロパティ。
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がマッピングされます。
すべてのプロパティ を参照してください。
サーバー
- 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.request-timeoutとRequestDeadlineは拡張です。 Spring がタイムアウトさせるのは接続 (Tomcat) と非同期リクエスト (spring.mvc.async.request-timeout) で、同期リクエストの処理ではありません。また、リクエストが行う呼び出しに期限が引き継がれることもありません。タイムアウト を参照してください。- 停滞したリクエストボディ には
server.connection-timeout(60 秒) の後に 408 が返ります。Tomcat では読み込みが失敗し、Spring は 400 を返します。 - 設定しない限り、接続数の上限はありません。
server.max-connectionsとserver.max-concurrent-requestsが上限を設定します (Tomcat のmax-connectionsはデフォルトで 8192)。どちらかを超えると、リクエストは待たされるのではなく、ただちにRetry-After付きの 503 で応答されます。過負荷 を参照してください。 - スレッドではなく isolate。 Tomcat のワーカースレッドは Bean を共有します。ここではサーバーは一つの isolate から応答します。
server.isolates.countは isolate を追加し、それぞれが自分の Bean でアプリケーション全体を実行するので、メモリー上のセッション、キャッシュ、カウンターは isolate ごとになります。isolate のプール を参照してください。 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)。シャットダウン を参照してください。
- Flutter アプリはデフォルトで
127.0.0.1で待ち受けます。 組み込みサーバー を参照してください。
プロキシの背後で
nativeとframeworkは同じことをします。 どちらも、Tomcat のRemoteIpValveと同様に、信頼されたプロキシの転送ヘッダーだけを適用します。Spring のForwardedHeaderFilter(framework) はすべての相手を信じます。- 信頼されたプロキシはアドレスと CIDR 範囲です (
server.forward-headers.trusted-proxies)。Tomcat の正規表現ではありません。 X-Forwarded-PrefixとX-Forwarded-Sslは読まれません。
リバースプロキシの背後で を参照してください。
コントローラーとパラメーター
- Spring より多くの起動時のチェック: パラメーターのないパス変数、何も埋められないパラメーター、無効な
@ExceptionHandlerは、問題の一覧とともに起動を止めます。起動時のチェック を参照してください。 - 必須か省略可能かは Dart のパラメーターで決まります。
requiredとdefaultValueではありません。null 許容のパラメーターはnullを受け取り、省略可能なパラメーターは Dart のデフォルト値を保ちます。 @ModelAttributeも、フォームのオブジェクトへのバインドもありません。 フォームのフィールドは、@RequestParam(一つのフィールド、リスト、またはすべてをMapとして) か@RequestBody() Map<String, String>でハンドラーに届きます。HttpSessionパラメーターはありません。 ハンドラーはrequest.getSession()でセッションを取得します。セッション を参照してください。- 独自の引数リゾルバーは組み込みのものより先に問い合わされます (Spring では後)。そのため、セキュリティスターターの
@AuthenticationPrincipalのように、スターターがどのパラメーターでも引き受けられます。WebMvcConfigurer を参照してください。 @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 を参照してください。@ControllerAdvice.of(basePackages: ...)は Java のパッケージの代わりにライブラリ URI のプレフィックス (package:shop/admin/) を受け取り、annotationsはコントローラーのアノテーションを型の完全一致で照合します。basePackageClassesはありません。@ControllerAdvice を参照してください。HandlerExceptionResolverはErrorResponse(またはnull) を返します。レスポンスに書き込んでModelAndViewを返すのではありません。組み込みの解決 (@ExceptionHandlerメソッド、ResponseStatusException) が先に行われ、リゾルバー Bean はその後に問い合わされます。HandlerExceptionResolver を参照してください。
ストリーム、アップロード、ダウンロード
- 宣言された
Stream<Uint8List>またはStream<List<int>>の戻り値は生のバイトです。 Spring MVC にはバイトストリームの戻り値はありません。Spring WebFlux はFlux<DataBuffer>を同じように書きます。その他のストリームはサーバー送信イベント (または NDJSON) です。ダウンロード を参照してください。 - イベントストリームは
:のコメント行で始まります。dart:ioはヘッダーを最初のボディのバイトと一緒に送るためです。クライアントはこれを無視します。サーバー送信イベント を参照してください。 - タイムアウトのない
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はバインドされません。アップロード を参照してください。 - バイト範囲はリクエストごとに一つ。 複数の範囲を指定すると、
multipart/byterangesではなくコンテンツ全体が返ります。コントローラーが返すResourceにはETagがありません (静的リソースにはあります)。
静的リソース
Spring の ResourceHttpRequestHandler より厳しく、少し機能が多くなっています。静的リソース を参照してください。
- ドットファイルは提供されません (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 で拒否されます。 - セッションは一つのプロセスのメモリーに置かれます。別の
HttpSessionRepositoryBean を宣言した場合を除きます。
セッション を参照してください。
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、またはcorsConfigurationSourceBean で設定します。
CORS を参照してください。
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 を参照してください。
テスト
MockMvcは名前付きの期待値を受け取ります (andExpect(status: 200, json: ...)、マッチャーも使えます)。status().isOk()とjsonPath(...)の代わりです。ApplicationContextRunnerはサーバーを起動しません。テストがspring.test.web-environment=random-portを設定した場合を除きます。
テスト を参照してください。
まだないもの
以下は計画されていますが、まだありません。
@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になります。