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 で、差し替え可能なファクトリーの背後にあります。ルーティングのコードはすべてジェネレーターがビルド時に書き出すため、実行時のリフレクションはありません。
セットアップ
# 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 ファイルで完結するアプリケーション:
// 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);
# lib/resources/application.properties
server.port=8080
spring.main.register-shutdown-hook=true
Book と NewBook には JSON のためのアノテーションは不要です。コントローラーが受け取り、返すクラスが同じパッケージにあれば、ジェネレーターはそれぞれをコントローラーでの使われ方に応じて記述します。返されるだけのクラスにはゲッターを、@RequestBody のクラスにはコンストラクターとセッターを (@Valid() 付きなら制約を持つプロパティのゲッターも) 記述します。JSON として書き出す Object など、ビルドから見えない値には、そのクラスに @Introspected() が必要です (JSON を参照)。
実行する
dart run build_runner build # bin/spring_gen/main.spring.dart を書き出す
dart run bin/main.dart
アノテーションを追加・変更したら build_runner を再実行します。コンテキストの準備ができるとサーバーが起動し、ロガー spring.web.server で次のログを出力します。
INFO Web server started on port 8080 (http)
続いて:
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) がマッピングされ、コンテキストの準備ができるとサーバーが起動します。 - コントローラーが先にチェックされます。 マッピングに誤りがあると、すべての問題の一覧とともに起動が止まります (起動時のチェック を参照)。
Ctrl+Cでサーバーがグレースフルに停止するのは、アプリケーションがシグナルでコンテキストを閉じる場合だけです。spring.main.register-shutdown-hook=trueを設定してください。シグナルを待ち受けると Dart プログラムが終了しなくなるため、Spring Boot と異なり、ここではデフォルトがfalseです (シャットダウン を参照)。- ポートが使用中の場合は、そのポートと変更すべきプロパティを示すレポートとともに起動が失敗します。
内容
はじめに:
- テスト: メモリ上の
MockMvc、または空きポートで動く実際のサーバー。
コントローラー:
- コントローラー: リクエストがメソッドに届くまで。
- @RestController: リクエストに応答するクラス。
- @RequestMapping と @GetMapping: パス、メソッド、そして
produces、consumes、headersの条件。 - @PathVariable: パスからの値。
- @RequestParam: クエリパラメーターとフォームのフィールド。
- @RequestBody:
@Valid()で検証される JSON ボディ。 - ヘッダー、クッキー、リクエスト:
@RequestHeader、@CookieValue、アノテーションのない引数。 - 戻り値: メソッドが返すものと、それがどんなレスポンスになるか。
- 起動時のチェック: アプリケーションの起動時に見つかる誤り。
エラー:
- エラー: デフォルトの応答、各エラーのステータス、ログ。
- ProblemDetail: RFC 9457 のエラーボディと、それを持つ例外。
- @ExceptionHandler: 例外を独自の応答に変換します。
- @ControllerAdvice: すべてのコントローラーに対する例外ハンドラー。
- HandlerExceptionResolver: ライブラリが独自の例外をマッピングする方法。
ストリームとファイル:
- サーバー送信イベント:
EventStream、Stream<T>、SseEmitter。 - アップロード:
multipart/form-data、@RequestPart、MultipartFile。 - ダウンロード:
RangeとLast-Modifiedに対応したResourceの戻り値。 - StreamingResponseBody: その場で書き出すボディと、バイトストリーム。
Web の機能:
- 静的リソース:
lib/resources/static/やディレクトリのファイル、シングルページアプリ。 - セッション:
HttpSession、そのクッキーと制限。 - フィルター: すべてのリクエストを囲む
WebFilterBean。 - WebMvcConfigurer: インターセプター、引数リゾルバー、CORS マッピング、リソースハンドラー。
- CORS:
@CrossOrigin、グローバルなルール、corsConfigurationSourceBean。
サーバー:
- サーバー:
server.*、起動と停止、ファクトリー。 - SSL: PEM ファイルによる HTTPS、クライアント証明書。
- 圧縮: 対応するクライアント向けの gzip。
- タイムアウト:
server.connection-timeoutとserver.request-timeout。 - 過負荷:
server.max-concurrent-requestsとserver.max-connections。ただちに返されるRetry-After付きの 503。 - isolate のプール:
server.isolates.count、一つのポートを担当する複数の isolate、それによって変わること。 - isolate のスケーリング:
IsolateScalerとserver.isolates.scaling=auto。 - 毎秒のリクエスト数: デバッグ機能
qps。 - リバースプロキシの背後で:
ForwardedとX-Forwarded-*ヘッダー。 - シャットダウン: グレースフルな停止と即時停止。
- ハンドラーマッピング: ディスパッチャーと独自の
HandlerMappingBean。 - WebSocket: 同じポートで動く
spring_boot_starter_websocketのエンドポイント。
リファレンス:
- すべてのプロパティ: スターターのすべてのキー。
- Spring との違い: Spring Boot と動作が異なる点。
Spring (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 との違い にあります。