flutter-networking

Flutter Networking

Flutter アプリ向けのネットワーキングエージェントです。既存のプロジェクト情報を、具体的な API 呼び出し、クライアント、サービス、リポジトリ、エラー処理、認証フロー、検証手順に変換します。このスキルをチュートリアルとして扱わず、調査、適応、実装またはレビューを行い、検証してください。

Core Contract

1. pubspec.yaml、lib/、および既存のネットワーキング、アーキテクチャ、状態管理、DI、認証、永続化、テストの規約を調べ、対象が Flutter または Dart のパッケージであることを確認します。
2. ネットワーキングスタックがまだ存在しない場合、またはユーザーが明示的に移行を依頼した場合を除き、プロジェクトで現在使用されているクライアントスタックを維持します。このスキルの http の例は、並行して別のクライアントを追加するのではなく、既存の Dio、Retrofit、Chopper、生成済みクライアント、またはカスタムラッパーに適応させてください。
3. 実装タスクでは、型付きデコード関数、明確なタイムアウト、明示的なステータス処理、利用可能な場合はキャンセルまたは破棄が可能なリソース、テスト可能な境界を備えた、小規模で注入可能なクライアント／サービスを優先します。
4. レビューやデバッグのタスクでは、広範なスタイルのアドバイスより先に、壊れたステータス処理、解放されていないクライアントやサブスクリプション、安全でないトークン保存、タイムアウトの欠落、汎用的な例外、大きなレスポンスの UI スレッド上での解析、重複する進行中のリクエスト、テストの不足を報告します。
5. UI のネットワーキング層は薄く保ちます。ウィジェットはコマンドの実行や状態の監視を行えますが、エンドポイント呼び出しはサービスが、データポリシーはリポジトリが、UI 状態の遷移は状態オブジェクト／ViewModel が担います。
6. リポジトリで通常使われているコマンドで検証します。コピーした Dart アセットのチェックでは、flutter analyze、対象を絞った flutter test、テンプレートのみの dart format --output=none --set-exit-if-changed を優先します。省略したチェックについては説明してください。

Clarification Rules

プロジェクトの情報から判断できない重要な決定事項がある場合に限り、ユーザーに質問してください。

• API コントラクト、エンドポイントのベース URL、認証方式、またはトークンのライフサイクルが不明な場合。
• リアルタイム動作について、再接続ポリシー、順序、配信保証、オフライン時の動作など、プロダクト上の仕様が必要な場合。
• キャッシュの鮮度、楽観的更新、ページネーション、または再試行ポリシーが、ユーザーに表示されるデータの正確性を左右する場合。
• プロジェクトに複数のネットワーキングスタックがすでにあり、対象が明確でない場合。

プロジェクトを利用できない場合、または Flutter プロジェクトではない場合は、提示されたコンテキストに基づいて実装計画またはレビューを行い、リポジトリについて事実を捏造せず、コードの検証を実施できなかったことを明記してください。

リソースの参照先

現在のタスクに必要なリファレンスとアセットのみを読み込んでください。

必要な内容	読み込むもの	用途
基本的な HTTP CRUD または JSON モデル	http-basics.md	GET/POST/PUT/DELETE、クエリパラメーター、型付きパース、FutureBuilder の例
認証ヘッダー、トークンの保存、ログイン、更新、OAuth	authentication.md	Bearer/basic/API key 認証、安全なトークン処理、更新フロー、認証リトライ
ステータスコード、例外、タイムアウト、リトライ、UI エラー	error-handling.md	API 例外モデル、タイムアウト／接続処理、リトライポリシー、ユーザー向けエラー
大きな JSON、キャッシュ、ページネーション、重複排除、計測	performance.md	compute()、キャッシュ TTL、リクエストの重複排除、ページネーション、計測
WebSocket 接続、JSON メッセージ、再接続、認証	websockets.md	チャネル、ストリームサブスクリプション、接続状態、再接続、安全なソケット
再利用可能な HTTP サービステンプレート	http_service.dart	ベース URL、デコード関数、タイムアウト、認証、DI への適合を調整してからコピー
リポジトリ／キャッシュのテンプレート	repository_template.dart	アプリに同等のリポジトリ／キャッシュ境界がない場合にのみコピー
単独で実行できる例	examples	参考用のスニペットとして使用し、インポート、状態管理、破棄、エラー処理を調整

コピーしたアセットはすべて、検証前に対象アプリのパッケージ名、リンター設定、 クライアントスタック、状態管理のスタイル、アーキテクチャに合わせて調整してください。

ネットワークのデフォルト設定

• 新しいシンプルなクライアントに限り、http: ^1.6.0 と web_socket_channel: ^3.0.3 を使用してください。既存の Dio、Retrofit、Chopper、または生成済みクライアントがある場合は、確立されたスタックに従ってください。
• クライアントはサービスの深い階層で生成せず、インジェクションしてください。所有する http.Client、WebSocket チャネル、ストリームサブスクリプション、タイマー、テキストコントローラーは閉じてください。
• エンドポイントの契約で認められる場合に限り、200..299 を成功として扱ってください。204 は空として処理し、モデルのメソッドは安全でないキャストを使わず、nullable または void にしてください。
• サービス／リポジトリ境界で JSON を型付きモデルにデコードしてください。大きなレスポンスにはバックグラウンドのアイソレートを使用し、小さなペイロードではアイソレートのオーバーヘッドを避けてください。
• リクエストにタイムアウトを設定し、一時的な障害に限ってリトライしてください。API が冪等である場合、またはユーザーがプロダクトのポリシーを確認した場合を除き、安全でない変更操作をリトライしないでください。
• 機密性の高いトークンは flutter_secure_storage: ^10.0.0 またはアプリが既に使用している安全なストレージに保存してください。アクセストークンをソースコード、shared_preferences、ログ、クラッシュレポートに保存しないでください。
• WebSocket には wss:// を使用してください。IOWebSocketChannel を使ったカスタム WebSocket ヘッダーは IO 専用です。Flutter web ではブラウザー互換の代替手段を用意してください。
• package:http では Accept-Encoding をデフォルトとして手動設定しないでください。プロジェクトで計測に基づく必要がある場合を除き、圧縮方式のネゴシエーションはプラットフォーム／クライアントに任せてください。

検証

実装やレビューを完了する前に、以下を確認します。

1. エンドポイントの呼び出しが、テスト可能なサービスまたはリポジトリを介して行われており、 UI コードが HTTP／WebSocket の生の詳細を直接扱っていないことを確認します。
2. すべてのリクエストに、ステータス処理、タイムアウト／エラー処理、 型付きの解析、または明示的な生レスポンスの契約があることを確認します。
3. 認証シークレットが、アプリの既存のセキュアストレージおよびライフサイクルのルールに従って 保存、更新されていることを確認します。
4. 変更対象のコードが所有するクライアント、チャネル、サブスクリプション、コントローラー、 タイマーが破棄されることを確認します。
5. 利用可能な範囲で、最も適切な検証を実行します。
   • flutter analyze
   • 変更したネットワーク／認証／リポジトリコードを対象とする、重点的な flutter test スイート
   • コピーした Dart アセットに対する dart format --output=none --set-exit-if-changed
   • 同梱のサンプルまたはテンプレートを変更した場合は、このスキルの scripts/verify-examples.sh
6. 実行したコマンド、失敗した項目、スキップしたチェック、残存するネットワーク関連のリスクを報告します。