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 つのパッケージが、同じアノテーションを反対の側から読みます。

語彙を独立したパッケージに置くことで、サーバー、クライアント、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.* です。

内容

Spring (Java) との対応

Spring では、これらの型は spring-web (アノテーション、ResponseEntity、HttpHeaders、ProblemDetail)、spring-webmvc、spring-websocket に分散しています。ここでは、ブラウザーを含め Dart が動くあらゆる場所で動く、一つの小さなパッケージです。アノテーションは Dart の形をとります。名前付きの属性には .of コンストラクターを使い、required も defaultValue もありません。

関連項目