
# spring_boot_starter_websocket

`spring_boot_starter_websocket` は、Spring for Dart に両側の WebSocket 接続を提供します。**クライアント**は、受信メッセージのためのメソッド (`@OnMessage`) と送信のためのメソッド (`@SendMessage`) を持つ抽象クラスで、他の Bean と同じように注入されます。接続は最初に必要になったときに開き、失われると再接続します。**サーバーのエンドポイント**は `@WebSocketEndpoint` の Bean、または `WebSocketConfigurer` を伴う Spring の `WebSocketHandler` で、`spring_boot_starter_web` がそのポートで配信します。

## 使う理由

WebSocket は開いたままなので、サーバーは何かが起きた瞬間にメッセージを送り出せます。チャットのメッセージ、価格、通知などです。手で扱うと、接続を開き、すべてのフレームをエンコード・デコードし、ネットワークが切れたら再び開くことになります。スターターがその作業を行います。ジェネレーターがビルド時にリフレクションなしでコードを書き、メッセージは `spring_core_dart` の `ObjectMapper` を通して JSON として読み書きされます。クライアントは VM、Flutter (モバイル、デスクトップ、Web)、ブラウザーで動きます。

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_websocket: ^0.9.0
  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       # MockWebSocketTransport、MockMvc.webSocket
  test: ^1.33.0
```

インポートは一つです。`package:spring_boot_starter_websocket/spring_boot_starter_websocket.dart` は `spring_boot_dart`、`spring_web_dart`、`spring_boot_starter_logging` を再エクスポートします。スターターは Web スターターに依存しないため、クライアントだけを持つ Flutter アプリはサーバーを起動しません。

## 例

クライアント:

```dart
@WebSocketClient('chat', url: r'${chat.url}')
abstract interface class ChatSocket {
  @OnMessage()
  Stream<ChatMessage> messages();         // JSON から読む受信メッセージ

  @SendMessage()
  Future<void> send(ChatMessage message); // JSON として送る
}

@Introspected()
class ChatMessage {
  const ChatMessage({required this.from, required this.text});

  final String from;
  final String text;
}

@Service()
@Log()
class Chat {
  Chat(this.socket);                       // 生成されたクライアント。他の Bean と同じく注入される

  final ChatSocket socket;

  // 購読すると接続が開く。誰かが購読している間は再接続する。
  void start() => socket.messages().listen((m) => log.info('${m.from}: ${m.text}'));

  Future<void> say(String text) => socket.send(ChatMessage(from: 'me', text: text));
}
```

```properties
chat.url=wss://chat.neon.books/ws
```

サーバーのエンドポイント:

```dart
@WebSocketEndpoint('/ws/rooms/{room}', allowedOrigins: ['https://chat.example'])
class ChatEndpoint {
  ChatEndpoint(this.sessions);

  final WebSocketSessionRegistry sessions;

  @OnMessage()
  void message(@PathVariable() String room, ChatMessage message) =>
      sessions.broadcast('/ws/rooms/{room}', message);   // 開いているすべてのセッションに
}
```

## 起動するもの

- スキャンされたパッケージの、**`@WebSocketClient` を持つすべての抽象クラス**が、インターフェースにちなんだ名前 (`ChatSocket` → `chatSocket`) の Bean になります。有効な `ws://` や `wss://` の URL を持たないクライアントや、別の種類のメソッドを持つクライアントは起動を止めます。
- **`@PhoenixChannel` の付いたすべての抽象クラス**も、同じように Bean になります。Phoenix サーバー、またはそのプロトコルを話すサービスのチャンネルです。`phoenixSocketFactory` Bean がそのソケットを渡します。[Phoenix Channels クライアント](phoenix.md) を参照してください。
- **`webSocketTransport` Bean**、`platformWebSocketTransport()`: VM と Flutter のモバイル・デスクトップでは `dart:io`、Web ではブラウザーの WebSocket です。
- **Web スターターがある場合:** すべての `@WebSocketEndpoint` と `WebSocketConfigurer` のハンドラーがマッピングされ、`WebSocketSessionRegistry` が開いているセッションを保持し、ハンドシェイクは Web のフィルターを通ります。
- **二つのモジュール。** クライアントは `springBootStarterWebsocketAutoConfiguration` にあり、すべてのプラットフォームに含まれます。サーバー側 (`webSocketSessionRegistry`、`webSocketHandlerMapping`) は `springBootStarterWebsocketServerAutoConfiguration` にあり、これは `native` だけです。つまりサーバーが動ける場所です。`@WebSocketClient` のためにこのスターターを使う Flutter の Web アプリは、サーバーのコードを持ちません。[一つのプラットフォームだけのモジュール](../spring-core-dart-generator/optimizations/build-conditions.md#一つのプラットフォームだけのモジュール) を参照してください。
- **シャットダウン時**にはすべての接続が閉じられます。`closeAsync()` はそれらが閉じるまで待ちます。

## 内容

- [クライアント](clients.md): `@WebSocketClient`、`@OnMessage`、`@SendMessage`、接続と再接続。
- [クライアントの設定](client-configuration.md): `spring.websocket.client.*`、ハンドシェイクのインターセプター、トランスポートとその制限。
- [Phoenix Channels クライアント](phoenix.md): `@PhoenixChannel`、`@OnEvent`、`@Push`、一つの接続の上の多数のトピック、`PhoenixSocket`。
- [サーバーのエンドポイント](server-endpoints.md): `@WebSocketEndpoint`、`@OnOpen`、`@OnMessage`、`@OnClose`、`@OnError`。
- [ハンドラー、オリジン、ブロードキャスト](handlers.md): `WebSocketHandler`、`WebSocketConfigurer`、`HandshakeInterceptor`、オリジンのチェック、`WebSocketSessionRegistry`。
- [テスト](testing.md): `MockWebSocketTransport` と `MockMvc.webSocket`。
- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md): Spring と動作が異なる点。

## Spring (Java) との対応

Spring には宣言的な WebSocket クライアントがありません。ハンドラーを書いて命令的なクライアントに渡すか、STOMP を使います。このスターターは代わりに `@FeignClient` のスタイルに従います。サーバーでは、Spring は `WebSocketHandler` (ここでも対応しています) か Jakarta の `@ServerEndpoint` クラスを登録します。`@WebSocketEndpoint` は、シングルトンの Bean で Jakarta の名前に従います。STOMP にはまだ対応していません。

## 関連項目

- [Web スターターの WebSocket](../spring-boot-starter-web/server/websocket.md)
- [spring_web_dart](../spring-web-dart/index.md)
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [Supabase Realtime](../spring-boot-starter-supabase/realtime.md)
- [ビルドに含まれるもの](optimizations.md)
