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)、ブラウザーで動きます。
セットアップ
# 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 アプリはサーバーを起動しません。
例
クライアント:
@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));
}
chat.url=wss://chat.neon.books/ws
サーバーのエンドポイント:
@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 サーバー、またはそのプロトコルを話すサービスのチャンネルです。phoenixSocketFactoryBean がそのソケットを渡します。Phoenix Channels クライアント を参照してください。webSocketTransportBean、platformWebSocketTransport(): VM と Flutter のモバイル・デスクトップではdart:io、Web ではブラウザーの WebSocket です。- Web スターターがある場合: すべての
@WebSocketEndpointとWebSocketConfigurerのハンドラーがマッピングされ、WebSocketSessionRegistryが開いているセッションを保持し、ハンドシェイクは Web のフィルターを通ります。 - 二つのモジュール。 クライアントは
springBootStarterWebsocketAutoConfigurationにあり、すべてのプラットフォームに含まれます。サーバー側 (webSocketSessionRegistry、webSocketHandlerMapping) はspringBootStarterWebsocketServerAutoConfigurationにあり、これはnativeだけです。つまりサーバーが動ける場所です。@WebSocketClientのためにこのスターターを使う Flutter の Web アプリは、サーバーのコードを持ちません。一つのプラットフォームだけのモジュール を参照してください。 - シャットダウン時にはすべての接続が閉じられます。
closeAsync()はそれらが閉じるまで待ちます。
内容
- クライアント:
@WebSocketClient、@OnMessage、@SendMessage、接続と再接続。 - クライアントの設定:
spring.websocket.client.*、ハンドシェイクのインターセプター、トランスポートとその制限。 - Phoenix Channels クライアント:
@PhoenixChannel、@OnEvent、@Push、一つの接続の上の多数のトピック、PhoenixSocket。 - サーバーのエンドポイント:
@WebSocketEndpoint、@OnOpen、@OnMessage、@OnClose、@OnError。 - ハンドラー、オリジン、ブロードキャスト:
WebSocketHandler、WebSocketConfigurer、HandshakeInterceptor、オリジンのチェック、WebSocketSessionRegistry。 - テスト:
MockWebSocketTransportとMockMvc.webSocket。 - すべてのプロパティ: スターターのすべてのキー。
- Spring との違い: Spring と動作が異なる点。
Spring (Java) との対応
Spring には宣言的な WebSocket クライアントがありません。ハンドラーを書いて命令的なクライアントに渡すか、STOMP を使います。このスターターは代わりに @FeignClient のスタイルに従います。サーバーでは、Spring は WebSocketHandler (ここでも対応しています) か Jakarta の @ServerEndpoint クラスを登録します。@WebSocketEndpoint は、シングルトンの Bean で Jakarta の名前に従います。STOMP にはまだ対応していません。