flutter-riverpod-arch

Flutter Riverpod アーキテクチャ

目的

Feature-First のディレクトリ構成、状態管理に Riverpod（コード生成を使用）、UI の構成に flutter_hooks ／ HookConsumerWidget を使用して、スケーラブルな Flutter アプリケーションを実装します。このアーキテクチャは、ドメイン駆動設計とクリーンアーキテクチャに着想を得た軽量なアプローチです。設計思想は Presentation、Domain、Infrastructure の 3 層で、このスキルにおけるコードレベルの表記は UI、UseCase、Repository です。データソースへのアクセスは Repository 内にカプセル化します。Repository のプロバイダーには @Riverpod(keepAlive: true) を、画面スコープの状態には @riverpod を適用します。

レイヤーの対応関係（正）

設計思想	コードレベルの表記
Presentation	UI
Domain	UseCase
Infrastructure	Repository

判断ロジック

タスクが UI、UseCase、Repository のどれに該当するか、機能固有か共通か、またどの Riverpod スコープが適切かを判断します。

構成と命名については architecture.md、Repository／UseCase の配置については providers.md、プロバイダーのスコープ規則については riverpod.md を参照してください。

手順

1. 機能の構成を計画する

機能を特定し、実装が共通か機能ローカルかを確認してから、コーディングを始める前にファイルを適切なレイヤーに配置します。

ディレクトリ構成と命名については architecture.md を参照してください。

2. Repository レイヤーを実装する

Repository レイヤーに Repository コードを実装し、Repository プロバイダーに関する Riverpod／プロバイダーの規則に従います。

Repository の実装の詳細については providers.md、プロバイダーのスコープ規則については riverpod.md を参照してください。

3. UseCase レイヤーを実装する

検証、オーケストレーション、UI に反映する状態変更のために、UseCase レイヤーに UseCase コードを実装します。

UseCase のパターンについては providers.md、プロバイダーのスコープ規則については riverpod.md を参照してください。

4. HookConsumerWidget で UI を構築する

このスキルで定められたパターンを使用し、Presentation レイヤーに UI を構築します。

ページとウィジェットの構成については presentation.md、ref.watch ／ ref.read については riverpod.md、ボタンとカーソルの規則については button.md を参照してください。

5. レスポンシブレイアウトを実装する

このスキルで定められたレスポンシブレイアウトの規則を適用します。

ブレークポイントの方針とレスポンシブレイアウトのパターンについては responsive.md を参照してください。

6. テストを作成する

このスキルのテストパターンを使用して、Repository、UseCase、コントローラー、ウィジェットの動作をテストします。

テストの構成、オーバーライド、フェイク／モックのパターンについては testing.md を参照してください。

制約

• HookConsumerWidget を優先する： このスキルでは、状態を持つページや複雑なウィジェットすべてに flutter_hooks と併用した HookConsumerWidget を使用します。Riverpod との連携がない、独立したローカル UI 状態に限り、StatefulWidget を使用できます。
• build 内で ref.read() を使用しない： ref.read() はイベントハンドラーまたはコールバック内でのみ使用してください。リアクティブな UI 状態を導出するために、build メソッドの先頭で使用してはいけません。
• イベントハンドラー内で ref.watch() を使用しない： ref.watch() は build() 内、またはプロバイダーの build() メソッド内でのみ使用してください。
• ビューにビジネスロジックを記述しない： ウィジェットクラスには、レイアウト、条件付きレンダリング、ナビゲーションのみを含めてください。データの変換と検証はすべて、ユースケースまたはリポジトリに記述する必要があります。
• リストのパターン： list.md で定義されているリストとスライバーのルールに従ってください。
• スタイル設定のみを目的とするボタンラッパーウィジェットは避ける： 固定のボタンスタイルを適用することだけを目的としたカスタムラッパーウィジェットは作成しないでください。ローディング状態や送信フローなどの動作をカプセル化する場合は、ラッパーを使用できます。
• 対象を絞った MediaQuery の静的メソッドを使用する： 不要な再ビルドを避けるため、MediaQuery.of(context) よりも MediaQuery.sizeOf、MediaQuery.paddingOf、MediaQuery.orientationOf などを優先してください。
• ページレベルのブレークポイントに LayoutBuilder を使用しない： MediaQuery.sizeOf を使用する ResponsiveLayout を使用してください。これにより、レイアウトの判定は親の制約ではなく、実際の画面幅に基づいて行われます。
• macOS/Web ではマウスカーソルを指定する： すべての Button バリアントに enabledMouseCursor: SystemMouseCursors.click を含めてください。すべての InkWell に mouseCursor: SystemMouseCursors.click を含めてください。
• コード生成は必須： @riverpod アノテーションを追加または変更した後は、必ず dart run build_runner build を実行してください。
• 命名規則： ファイルとディレクトリには snake_case を使用します。クラスには UpperCamelCase を使用します。ページクラス名の末尾は Page、リポジトリクラス名の末尾は Repository とします。ユースケースクラス名には動詞と名詞の形式を使用します（例：FetchPosts、CreatePost）。

参考ファイル

• architecture.md — プロジェクト構造、ディレクトリ構成、命名規則
• providers.md — リポジトリとユースケースの実装パターン
• riverpod.md — プロバイダーの種類、ref.watch と ref.read の使い分け、キャッシュ、コード生成
• presentation.md — ページ構成、ナビゲーション、フックの使用方法、エラー処理
• testing.md — テストパターン、モック戦略、ProviderContainer の使用方法
• button.md — ボタンのパターン、styleFrom、macOS/Web のホバーカーソル
• list.md — ListView.builder、プルトゥリフレッシュ、スライバーを使用したページネーション
• responsive.md — ブレークポイント、ResponsiveLayout、プラットフォーム固有のレイアウト