
# spring_web_dart

`spring_web_dart` は、Spring for Dart のパッケージに共通する Web の語彙です。HTTP 呼び出しを記述するアノテーション、HTTP そのものの型 (ヘッダー、ステータスコード、メディアタイプ、レスポンスボディ、エラー)、そして VM、Flutter、ブラウザーで HTTP と WebSocket のリクエストを送るクライアントです。

## 使う理由

HTTP のエンドポイントは、Dart のメソッドに付けたアノテーションで一度だけ記述します。

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

他の 2 つのパッケージが、同じアノテーションを反対の側から読みます。

- [spring_boot_starter_web](../spring-boot-starter-web/index.md) は Web サーバーです。`@RestController` クラスでは、上のメソッドは `GET /books/978-0` に応答します。
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md) は HTTP クライアントです。`@FeignClient` インターフェースでは、上のメソッドは `GET /books/978-0` を送り、応答を `Book` に読み込みます。

語彙を独立したパッケージに置くことで、サーバー、クライアント、WebSocket スターター、ライブラリが互いに依存せずにそれを共有でき、Flutter アプリはサーバーなしでクライアントを使えます。

## セットアップ

ほとんどのアプリケーションはこのパッケージを手で追加しません。Web、Feign、WebSocket のスターターとともに来て、それらが再エクスポートします。HTTP と WebSocket のクライアントだけが欲しい場合や、アノテーションを読んだりサーバーの型を扱ったりするライブラリを書く場合に、直接追加してください。

```yaml
# 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 リクエストを送れます。

```dart
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.*` です。

## 内容

- [マッピングのアノテーション](mapping-annotations.md): サーバーとクライアントのための `@GetMapping`、`@PathVariable`、`@RequestParam`、`@RequestBody` など。
- [コントローラーのアノテーション](controller-annotations.md): `@RestController`、`@ResponseStatus`、`@ExceptionHandler`、`@ControllerAdvice`、`@CrossOrigin`。
- [HTTP の型](http-types.md): `ResponseEntity`、`HttpHeaders`、`HttpStatus`、`MediaType`、`ProblemDetail`、マルチパート。
- [HTTP トランスポート](http-transport.md): `HttpTransport`、タイムアウト、ストリーミングのレスポンス。
- [サーバー送信イベント](server-sent-events.md): `EventStream<T>`、再接続、デコーダー。
- [WebSocket トランスポート](websocket-transport.md): `WebSocketTransport`、`WebSocketSession`、制限。
- [サーバー側](server-side.md): `ServerHttpRequest`、`HandlerMapping`、`PathPattern`、`RequestDeadline`、`AllowedOrigins`。
- [テスト](testing.md): `MockHttpTransport`、`MockWebSocketTransport`、サーバーのモック。
- [Spring との違い](differences.md): Spring Web と動作が異なる点。

## Spring (Java) との対応

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

## 関連項目

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [spring_boot_starter_websocket](../spring-boot-starter-websocket/index.md)
