spring_web_dart
spring_web_dart は、Spring for Dart のパッケージに共通する Web の語彙です。HTTP 呼び出しを記述するアノテーション、HTTP そのものの型 (ヘッダー、ステータスコード、メディアタイプ、レスポンスボディ、エラー)、そして VM、Flutter、ブラウザーで HTTP と WebSocket のリクエストを送るクライアントです。
使う理由
HTTP のエンドポイントは、Dart のメソッドに付けたアノテーションで一度だけ記述します。
@GetMapping('/books/{isbn}')
Future<Book> find(@PathVariable() String isbn);
他の 2 つのパッケージが、同じアノテーションを反対の側から読みます。
- spring_boot_starter_web は Web サーバーです。
@RestControllerクラスでは、上のメソッドはGET /books/978-0に応答します。 - spring_boot_starter_feign は HTTP クライアントです。
@FeignClientインターフェースでは、上のメソッドはGET /books/978-0を送り、応答をBookに読み込みます。
語彙を独立したパッケージに置くことで、サーバー、クライアント、WebSocket スターター、ライブラリが互いに依存せずにそれを共有でき、Flutter アプリはサーバーなしでクライアントを使えます。
セットアップ
ほとんどのアプリケーションはこのパッケージを手で追加しません。Web、Feign、WebSocket のスターターとともに来て、それらが再エクスポートします。HTTP と WebSocket のクライアントだけが欲しい場合や、アノテーションを読んだりサーバーの型を扱ったりするライブラリを書く場合に、直接追加してください。
# pubspec.yaml
dependencies:
spring_web_dart: ^0.9.0
唯一の依存関係は spring_core_dart で、それ自体はコード生成を必要としません。インポート:
| インポート | 含むもの |
|---|---|
package:spring_web_dart/spring_web_dart.dart |
すべて。platformHttpTransport() と platformWebSocketTransport() を含む。 |
package:spring_web_dart/io.dart |
IoHttpTransport、IoWebSocketTransport (dart:io)。 |
package:spring_web_dart/browser.dart |
FetchHttpTransport、BrowserWebSocketTransport。 |
package:spring_web_dart/testing.dart |
MockHttpTransport、MockWebSocketTransport、MockServerHttpRequest、MockServerHttpResponse、MockMultipartFile、WebSocketSessionPair。 |
例
このパッケージだけで、どのプラットフォームからでも HTTP リクエストを送れます。
import 'package:spring_web_dart/spring_web_dart.dart';
Future<void> main() async {
final transport = platformHttpTransport();
final response = await transport.send(
HttpRequest(
method: HttpMethod.get,
url: Uri.parse('https://api.neon.books/books/978-0'),
headers: HttpHeaders({HttpHeaders.acceptHeader: MediaType.applicationJson}),
timeout: const Duration(seconds: 5), // 遅いサーバーはあきらめる
),
);
// どのステータスもレスポンス。例外を投げるのはネットワークの失敗だけ。
if (response.statusCode.is2xxSuccessful) print(response.bodyText);
transport.close();
}
HttpHeaders、HttpStatus、HttpRequest、HttpResponse は dart:io のクラスと同じ名前です。両方が必要なファイルでは、dart:io をプレフィックス付きでインポートするか (import 'dart:io' as io;)、それらを hide してください。
設定
spring_web_dart は独自のプロパティを持ちません。型のライブラリで、コードで設定します (platformHttpTransport(connectTimeout:)、IoWebSocketTransport(maxTextMessageSize:))。それを使うスターターがプロパティを読みます。Web スターターでは server.* と spring.mvc.*、Feign スターターでは spring.feign.*、WebSocket スターターでは spring.websocket.client.* です。
内容
- マッピングのアノテーション: サーバーとクライアントのための
@GetMapping、@PathVariable、@RequestParam、@RequestBodyなど。 - コントローラーのアノテーション:
@RestController、@ResponseStatus、@ExceptionHandler、@ControllerAdvice、@CrossOrigin。 - HTTP の型:
ResponseEntity、HttpHeaders、HttpStatus、MediaType、ProblemDetail、マルチパート。 - HTTP トランスポート:
HttpTransport、タイムアウト、ストリーミングのレスポンス。 - サーバー送信イベント:
EventStream<T>、再接続、デコーダー。 - WebSocket トランスポート:
WebSocketTransport、WebSocketSession、制限。 - サーバー側:
ServerHttpRequest、HandlerMapping、PathPattern、RequestDeadline、AllowedOrigins。 - テスト:
MockHttpTransport、MockWebSocketTransport、サーバーのモック。 - Spring との違い: Spring Web と動作が異なる点。
Spring (Java) との対応
Spring では、これらの型は spring-web (アノテーション、ResponseEntity、HttpHeaders、ProblemDetail)、spring-webmvc、spring-websocket に分散しています。ここでは、ブラウザーを含め Dart が動くあらゆる場所で動く、一つの小さなパッケージです。アノテーションは Dart の形をとります。名前付きの属性には .of コンストラクターを使い、required も defaultValue もありません。