state-management-riverpod

状態管理（Riverpod）

状態と依存関係の注入には、Riverpod 3.x という 1 つの仕組みを使います。各機能には Notifier／AsyncNotifier／StreamNotifier の ViewModel を 1 つ置き、不変の状態値を公開します。シンプルな ConsumerWidget はその状態を読み取ります。ウィジェットが保持するのは一時的な UI 状態のみです。永続する変更はすべて、1 つのリポジトリ（唯一の書き込み経路）を通します。このスキルでは、まず状態管理ライブラリに依存しない基本事項を説明し、次に Riverpod の「使い方」、最後に公式 Flutter ガイドのスタックで使われる Provider／ChangeNotifier の補足を説明します。

作業内容に応じて、次のリファレンスを確認してください。

• references/ownership-and-lifecycle.md — 所有権の表（どのプロバイダー形式を使うか）、family／autoDispose／onDispose のルール、コンポジションルートでの DI。
• references/reads-and-side-effects.md — watch と read と listen と select の使い分け、古いクロージャの落とし穴、void のアクションメソッド、ref.mounted／BuildContext のガード。
• references/riverpod3-api-and-testing.md — Riverpod 3.x の API 変更（legacy の移行先、overrideWithValue、retry、ProviderContainer.test）、2023 年のチュートリアルで誤っている点、テストの境界。

PR の前に scripts/ban-legacy-providers.sh を実行してください。

絶対に守るルール

これらは状態管理ライブラリに関係なく適用されます。

1. 機能ごとに ViewModel を 1 つ置き、不変の状態値を 1 つ持たせます。 状態は値の等価性を持つ値型（freezed／sealed と copyWith）にし、可変フィールドの寄せ集めにはしません。機能間で共有する状態は ViewModel ではなくリポジトリに置きます。同じ事実を 2 つの ViewModel が所有すると、食い違う 2 つの事実になってしまいます。
2. 状態は非公開にし、意図を表すメソッドを通じてのみ変更します。 ウィジェットから状態のフィールドに直接触れてはいけません。ビューは notifier.rename(id, name) を呼び、状態を直接設定することはありません。これが状態を変更する唯一の入口であり、すべての変更を 1 か所でレビューできます。
3. 状態遷移のたびに 新しい 値を割り当てます。 値の等価性を使うリスナーは値で差分を検出します。インスタンスを直接変更して同じ参照を再割り当てすると変更が検出されず、UI が気づかれないまま古い状態になります。必ず copyWith で新しいインスタンスを作成します。
4. 保存するのではなく、導出します。 既存の状態から計算できる値（合計、フィルター後の件数、連続記録など）はゲッターまたはストリームの射影にします。別のフィールドとして保存してはいけません。導出値を保存すると、第 2 の真実の情報源となり、同期がずれていきます。
5. 書き込み経路は 1 つにします。 永続する変更はすべて、トランザクションで永続化し、コミットが完了してからのみ戻るリポジトリメソッド 1 つを通します。UI が更新されるのはストリームが再通知されるためであり、楽観的に再公開するためではありません。公開前に永続化することで、クラッシュ時の安全性を規律に頼らず構造的に確保できます。
6. 単方向データフローにします。 意図 → ViewModel → リポジトリ／サービス → 新しい状態 → ビュー、という流れにします。ビューは読み取ったデータを変更せず、経路を飛ばして上流に戻すこともありません。データは下流へ、イベントは上流へ流れます。
7. 抽象に依存させ、注入します。決して自分で生成しません。 ViewModel にはリポジトリ／サービス／クロックを渡します。稼働中の依存オブジェクトを new したり、BuildContext を保持したりしてはいけません。これにより、フェイクを使ったテストやフレーバーごとの差し替えが可能になります。
8. 非同期状態は、分散したフラグではなく明示的な状態としてモデル化します。 1 つの AsyncValue（またはステータス enum ＋ データ ＋ エラー）を網羅的に描画します。状態の半端な設定や不可能な状態を表せてしまう isLoading／hasError のブール値をあちこちに散在させてはいけません。
9. 削除時には参照を連鎖的にクリーンアップします。 エンティティを削除するときは、そのエンティティへのすべての参照（割り当て、外部キー、選択状態）も取り除きます。削除済みの親を指す項目は、後からクラッシュを引き起こす潜在的な原因です。孤立した項目を黙って削除してはいけません。明示的に別の場所へ移すか、割り当てを解除します。
10. 状態ロジックで DateTime.now() を使いません。 「現在時刻」は package:clock の Clock を注入して渡し、clockProvider として公開します。これにより、時間依存の動作をテストで決定的にできます（clockProvider.overrideWithValue(Clock.fixed(t))）。DateTime.now() も、独自の ClockService も使いません。clockProvider の差し替え口は service-boundary-and-native が担当します。

Riverpod：適切な形を選ぶ

所有するものに合わせてプロバイダーの形を選びます（表全体は references/ownership-and-lifecycle.md を参照してください）。

所有するもの	形
ライブクエリを基にした機能ごとのプレゼンテーション状態	build() がリポジトリのストリームを返す StreamNotifier
ストリームではない、機能ごとのプレゼンテーション状態	1 つの不変値を扱う Notifier / AsyncNotifier
DB のリアクティブな投影	リポジトリ／DAO のストリームを扱う StreamProvider（保存しない）
注入するコラボレーター（リポジトリ、サービス、Clock）	通常の Provider（DI）
エンティティ／セッションごとの状態	Notifier/AsyncNotifier/StreamNotifier の .family + .autoDispose

デフォルトでは手書きのプロバイダー（StreamNotifierProvider/AsyncNotifierProvider(...)、.autoDispose/.family 修飾子）を使用します。@riverpod によるコード生成は任意の利便機能であり、デフォルトではありません（リファレンスを参照）。Riverpod 3.0 の API のみを使用します。基底クラスは Notifier/AsyncNotifier/StreamNotifier です。autoDispose/family はプロバイダーの修飾子であり、基底クラスの AutoDispose*/*Family は使用しません（3.0 で削除されました）。

// features/task — one StreamNotifier ViewModel: build() returns the LIVE repo stream,
// so a committed write re-emits and the UI updates with no manual republish (D6).
class TaskListNotifier extends StreamNotifier<TaskListState> {
  @override
  Stream<TaskListState> build() {
    final filter = ref.watch(taskFilterProvider);          // in-session filter, its own Notifier
    return ref.watch(taskRepositoryProvider).watchAll()    // the live source of truth
        .map((tasks) => TaskListState(tasks: tasks, filter: filter));
  }

  // Durable act routes through the single write path. void so the call site never drops
  // the Future; no `state = ...` — the committed write makes watchAll() re-emit.
  void complete(TaskId id) =>
      unawaited(ref.read(taskRepositoryProvider).markComplete(id).catchError(_report));

  void _report(Object error, StackTrace stack) {/* surface via a logger — never swallow */}
}

final taskListNotifierProvider =
    StreamNotifierProvider.autoDispose<TaskListNotifier, TaskListState>(
        TaskListNotifier.new);

// The reversible in-session filter is its own tiny Notifier (manual NotifierProvider).
class TaskFilterNotifier extends Notifier<TaskFilter> {
  @override
  TaskFilter build() => TaskFilter.all;
  void set(TaskFilter f) => state = f; // watched by build() above; re-projects the stream
}

final taskFilterProvider =
    NotifierProvider<TaskFilterNotifier, TaskFilter>(TaskFilterNotifier.new);

Riverpod：プロバイダーは DI（例外をスローする継ぎ目）

ViewModel はプロバイダーからコラボレーターを読み取り、コンポジションルートで実際の実装を一度だけ配線します。プレースホルダーの継ぎ目はオーバーライドされるまで例外をスローするため、依存関係の配線漏れは、テスト内で実サービスをひそかに構築する代わりに、最初の読み取り時に明確に失敗します。

// A seam: throws until a flavor main() overrides it. One live impl per flavor.
final databaseProvider = Provider<AppDatabase>(
  (ref) => throw UnimplementedError('override databaseProvider in main()'),
);

final taskRepositoryProvider = Provider<TaskRepository>(
  (ref) => TaskRepository(ref.watch(databaseProvider)), // inject, never `new` a live DB here
);

// main.dart — the ONLY place live collaborators are constructed.
void main() {
  final db = AppDatabase.open();
  runApp(ProviderScope(
    overrides: [databaseProvider.overrideWithValue(db)],
    child: const App(),
  ));
}

プロバイダーを追加する前に、コンストラクター引数で済ませられないか考えてください。プロバイダー数の増加は進歩ではなく、設計上の懸念事項です。通常のプロバイダーでは必要性を表現できない場合に限り、family／スコープ設定／コード生成を使用します。

Riverpod：読み取り — watch / read / listen

詳しい理由は references/reads-and-side-effects.md を参照してください。

• ref.watch(p) / ref.watch(p.select((s) => s.field)) — build() 内で表示に使用します。.select を使うと、1 つのフィールドの変更に再ビルドを絞り込めます。大きなウィジェットの先頭でコントローラー全体を watch しないでください。
• ref.read(p.notifier) — コールバック（onTap、onPressed）内で使用します。build() 内で値を read すると古いデータのまま固定され、コールバック内で watch すると予期せず再ビルドされます。
• ref.listen(p, ...) — build() 内で、変更時の副作用（遷移、スナックバー表示）に使用します。build() から副作用を直接実行しないでください。

class TaskCounter extends ConsumerWidget {
  const TaskCounter({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final n = ref.watch(taskListNotifierProvider.select((s) => s.value?.openCount ?? 0));
    return Text('$n');
  }
}

古いクロージャーの落とし穴： ref.watch した値を onTap クロージャーにキャプチャしないでください。安定したキーを渡し、タップ時に ref.read で解決します。素早く再タップすると、キャプチャした値がひそかに前のエンティティを対象にしますが、これを検出するリンターはありません。

// WRONG — acts on a stale item after a re-render.
onTap: () => ref.read(p.notifier).complete(task),
// RIGHT — id is stable; resolve now.
onTap: () => ref.read(p.notifier).complete(task.id),

アクション経路のメソッドは void を返します。 onTap: () => notifier.doThing() のようなアロー関数は「返す」Future があっても、ターゲット型が VoidCallback のため、discarded_futures も unawaited_futures も満たしません。その結果、Future とそのエラーが破棄されます。意図を示すメソッドを void にすれば、この落とし穴を回避できます。非同期処理は、その内部で unawaited(_run().catchError(_report)) を使って開始します。async-safety を参照してください。

Riverpod：ライフサイクルと破棄

• エンティティ／セッションごとの状態は、安定した等価性を持つ値（ID または @freezed の引数レコード）をキーとする .family を使い、ミュータブルなオブジェクトは使いません。また、重いセッション状態がアンマウント時に破棄されるよう .autoDispose を指定します。
• アプリスコープのシングルトン（データベース、エンジン、サービス）は通常の Provider を使い、autoDispose は指定しません。
• await の後の書き込みは ref.mounted で保護します（use_build_context_synchronously に相当する Riverpod の仕組みです）。
• 所有するリソース（ストリーム、コントローラー、ネイティブハンドル）は ref.onDispose で解放します。Riverpod は StreamProvider のサブスクリプションを管理するため、手動で管理する必要はありません。

Riverpod：アクセシビリティの状態はプロバイダーを経由しません

MediaQuery.boldTextOf(context) ／ .textScalerOf(context) ／ .highContrastOf(context) は、プロバイダー経由ではなく、ウィジェットのビルド時に読み取ってください。MediaQuery は適切に無効化されるよう設計された InheritedWidget です。これをプロバイダー経由にすると、プロバイダー本体で BuildContext を使うか、1 フレーム古い値を手動で同期することになります。アプリ／ドメインの状態には Riverpod を、プラットフォーム／アクセシビリティの状態には BuildContext を使用してください。accessibility-as-code を参照してください。

アンチパターン

• レガシープロバイダー — StateProvider ／ StateNotifierProvider ／ ChangeNotifierProvider（flutter_riverpod/legacy.dart に移動済み）、または Riverpod と併用する get_it ／ package:provider ／ Bloc の追加。DI／状態管理の仕組みを二つ使うのは、一つに絞るより明らかに劣ります。
• プロバイダー本体にビジネスロジックを置くこと。 プロバイダーは薄い接続層です。ロジックは ViewModel、エンジン、リポジトリに置いてください。
• 状態の値をその場で変更して、同じインスタンスを再代入すること。 値の等価性を使うリスナーには変更が認識されません。
• 大きなウィジェットの先頭で ref.watch すること。 フィールドが変わるたびにサブツリー全体が再構築されます。.select または末端の ConsumerWidget を使ってください。
• アプリ／ドメインの状態に setState() を使うこと。 setState ／ローカルの State は、一時的な UI 状態（トグルやアニメーション実行中フラグなど）にのみ使います。
• 確定前に楽観的に再公開すること。 再公開と確定の間にクラッシュすると、ディスクには一度も保存されていない事実が表示されます。
• 依存オブジェクトを new する、BuildContext を保持する、画面遷移する、またはスナックバーを表示する ViewModel。 依存オブジェクトは注入し、状態を公開し、ビュー（またはルーターのリダイレクト）に反応させてください。
• 変更可能なオブジェクトを family のキーに使うこと、アプリスコープのシングルトンに autoDispose を設定すること、または本来追加すべきでない autoDispose を取り消すために keepAlive() を使うこと。

完了の定義

• 機能の状態は、不変値を扱う単一の Notifier ／ AsyncNotifier ／ StreamNotifier で管理し、ウィジェットが保持するのは一時的な UI 状態のみです。
• 状態は非公開にし、すべての変更は新しい値を代入するインテントメソッドを経由します。その場での変更はありません。
• 派生値はゲッター／ストリームの射影で表現し、フィールドとして保存しません。
• 非同期状態は単一の AsyncValue ／ステータスとして網羅的に描画し、独立したローディング／エラーのブール値は使いません。
• 永続化を伴う変更はすべて、確定してから戻るリポジトリメソッドで行います。確定前の楽観的な再公開はありません。
• 表示には ref.watch ／ .select、コールバックには ref.read(p.notifier)、副作用には ref.listen を使います。ウィジェット先頭で広範囲に watch したり、取得時の値をクロージャーに取り込んだりしません。
• 依存オブジェクトはプロバイダー経由で注入し、置き換えられるまでは接続箇所が例外を送出します。実運用の実装は main でフレーバーごとに一度だけ接続し、ViewModel では BuildContext ／ DateTime.now() を使いません。
• エンティティごとのプロバイダーは、安定した値をキーとする family を使って autoDispose を設定します。アプリのシングルトンには通常のプロバイダーを使い、リソースは ref.onDispose で解放します。
• legacy.dart、get_it、package:provider、Bloc のインポートはありません（scripts/ban-legacy-providers.sh が成功します）。

関連するスキル

• flutter-architecture — 機能優先の DAG において、ViewModel、リポジトリ、書き込み経路がどこに位置するかを説明します。
• error-handling-typed-results — リポジトリのメソッドが例外を投げる代わりに返す、Result／Failure の中核部分を扱います。
• async-safety — Future を破棄することで生じる問題、mounted ガード、サブスクリプションやタイマーの破棄を扱います。
• persistence-drift — StreamProvider が投影する Drift ストリームと、変更ごとに 1 つのトランザクションを使う書き込み経路を扱います。
• service-boundary-and-native — あらゆる副作用とネイティブチャネルに対する、例外を投げる境界のプロバイダーパターンを扱います。これらの ViewModel が DateTime.now() の代わりに参照する clockProvider（package:clock）の境界も担います。
• widget-composition — この状態を読み取る、状態を持たない ConsumerWidget の View を扱います。
• accessibility-as-code — このスキルが共同で担う分担を扱います。アプリ／ドメインの状態には Riverpod を使い、プラットフォーム／アクセシビリティの状態は MediaQuery／BuildContext から読み取り、プロバイダーは使いません。
• value-objects-money-and-units — 決定論的な時間処理のために Clock パラメーターを受け取る値型を扱います。
• app-startup-and-bootstrap — ProviderScope のオーバーライドを配線するコンポジションルートを扱います。

参考資料

• Riverpod のドキュメント
• Riverpod — 3.0 への移行
• Flutter — アプリ アーキテクチャガイド（MVVM）
• Flutter — シンプルなアプリの状態管理

Provider／ChangeNotifier 付録

Flutter 公式ガイドのスタック（package:provider と ChangeNotifier）では、仕組みだけが異なり、同じ 10 個のルールが適用されます。

• ViewModel = ChangeNotifier、新しい状態 = すべてのフィールドを設定した後に notifyListeners() を呼び出します（論理的な変更ごとに必ず 1 回だけ呼び出し、更新の途中やループ内では呼び出しません）。
• 状態は非公開にし、不変な形で公開します。 フィールドは _private にし、読み取り専用のゲッターを公開します。List.unmodifiable(...) を返し、変更可能なコレクションを渡さないでください。
• DI = 抽象型をコンストラクターインジェクションで注入し、画面より上位で Provider／ProxyProvider を使って配線します（画面を閉じると自動破棄されます）。コンテナーとして get_it を使わないでください。
• 読み取り = 表示には context.select／Consumer／Selector、コールバックには context.read を使います。didChangeDependencies またはコールバック内で読み取り、initState では読み取らないでください。
• ガード = await の後に notifyListeners() を呼び出す前に _disposed フラグを確認します。サブスクリプションをキャンセルし、所有するコントローラーは dispose() で破棄します。

enum ViewStatus { idle, loading, ready, error }

class TaskListViewModel extends ChangeNotifier {
  TaskListViewModel(this._repo);            // injected abstraction
  final TaskRepository _repo;

  ViewStatus _status = ViewStatus.idle;
  ViewStatus get status => _status;
  List<Task> _tasks = const [];
  List<Task> get tasks => List.unmodifiable(_tasks); // immutable view
  int get openCount => _tasks.where((t) => !t.done).length; // derive, don't store

  Future<void> load() async {
    _status = ViewStatus.loading; notifyListeners();
    try {
      _tasks = await _repo.load();
      _status = ViewStatus.ready;
    } catch (_) {
      _status = ViewStatus.error;
    }
    notifyListeners();                        // exactly one, after all fields set
  }

  Future<void> complete(TaskId id) async {
    await _repo.markComplete(id);             // single write path
    _tasks = [for (final t in _tasks) t.id == id ? t.copyWith(done: true) : t];
    notifyListeners();
  }
}