ref.watch: 監視して自動再描画

class HomeScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final routineListAsync = ref.watch(routineListProvider);

    return Scaffold(
      body: routineListAsync.when(
        loading: () => CircularProgressIndicator(),
        error: (e, _) => Text('エラー: $e'),
        data: (list) => ListView(...),
      ),
    );
  }
}

ref.watch は build() メソッド内で使う。値が変わると自動で build() が再実行される。

ref.read: 1回だけ取得

Future<void> _onRoutineTap(
  BuildContext context, WidgetRef ref,
  RoutineWithExercises data,
) async {
  await ref.read(activeWorkoutProvider.notifier).startSession(data);
  if (!context.mounted) return;
  Navigator.of(context).push(...);
}

build内 / コールバック内の使い分けルール

実際の HomeScreen から、watch と read の使い分けを整理する:

class HomeScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // build 内 = ref.watch（画面の描画に必要なデータ）
    final routineListAsync = ref.watch(routineListProvider);
    return Scaffold(...);
  }

  Future<void> _onRoutineTap(...) async {
    // コールバック内 = ref.read（アクションの実行）
    await ref.read(activeWorkoutProvider.notifier).startSession(data);
  }
}

覚え方:

• build 内: 「見続ける」必要がある → ref.watch
• コールバック内: 「やる」だけ → ref.read

ref.listen: 変化した瞬間に副作用を実行

ref.listen は「値が変わった瞬間に何かを実行する」ためのもの。watch のように再描画はせず、コールバックを呼ぶだけ。

// 例: セッション完了時にスナックバーを表示する
ref.listen(activeWorkoutProvider, (prev, next) {
  if (prev != null && next == null) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('セッション完了!')),
    );
  }
});

Provider中間層の役割: 飛ばすとどうなる?

筋トレメモの「ルーティン一覧表示」の流れを見てみよう:

// 実際の構造（Provider中間層あり）
HomeScreen
  └─ ref.watch(routineListProvider)
       └─ routineListProvider
            └─ ref.watch(routineRepositoryProvider)
                 └─ routineRepositoryProvider
                      └─ ref.watch(appDatabaseProvider)

もし Provider を飛ばして直接 DB にアクセスしたら?

// NG: Provider を飛ばした例
class HomeScreen extends ConsumerWidget {
  Widget build(context, ref) {
    final db = ref.watch(appDatabaseProvider);
    // 画面内で直接SQL相当の操作...
    return FutureBuilder(
      future: db.select(db.routines).get(),
      ...
    );
  }
}

失われるもの:

• PR判定ロジック: completeSession() 内の1RM計算と過去最高比較 — Repository/Notifier がないと UI に書くことに
• サマリー計算: totalVolume、totalFilledSetCount などの集計 — 全画面で重複コードになる
• 状態管理: セッション開始/セット更新/完了の一連の流れ — 各画面がバラバラに管理することに
• テスト容易性: Repository を override してモックDBでテストする手段が失われる

Notifier とは: 状態 + 操作メソッド

3-1で見た Provider は「値を返すだけ」だった。Notifier は「状態を持ち、メソッドで変更できる」Provider。

build() メソッド: 初期状態を決める

@Riverpod(keepAlive: true)
class ActiveWorkoutNotifier extends _$ActiveWorkoutNotifier {
  @override
  ActiveWorkoutState? build() => null;
}

ポイント:

• build() は Notifier の「初期状態」を返すメソッド
• 戻り値の型 (ActiveWorkoutState?) が、この Notifier が管理する state の型になる
• null = 「セッション未開始」を表現（null safety の活用）
• keepAlive: true = 画面遷移しても状態を保持（ワークアウト途中で画面を閉じても消えない）

state の更新: copyWith パターン

Notifier では state = ... で状態を更新する。イミュータブルなので、毎回新しいオブジェクトを作る:

/// セットの重量を更新
void updateWeight(int exerciseIndex, int setIndex, double weight) {
  if (!_isValidSetIndex(exerciseIndex, setIndex)) return;
  final sets = state!.exercises[exerciseIndex].sets;
  final newSets = [
    for (var i = 0; i < sets.length; i++)
      if (i == setIndex) sets[i].copyWith(weight: weight) else sets[i],
  ];
  state = _withUpdatedSets(exerciseIndex, newSets);
}

state = 新しい値 を実行すると:

1. Riverpod が「状態が変わった」ことを検知
2. ref.watch している全Widget が自動で再描画される

入力パラメータ から 状態フィールド への変換

Notifier で最も重要なパターン: 外部から受け取ったデータを、内部の状態フィールドに変換する。

Future<void> startSession(
  RoutineWithExercises data, {
  DateTime? targetDate,  // 入力パラメータ
}) async {
  state = ActiveWorkoutState(
    routineId: data.routine.id,
    routineName: data.routine.name,
    startedAt: targetDate ?? DateTime.now(),  // パラメータ → 状態フィールド
    exercises: data.exercises.map((e) {
      return ActiveExerciseData(
        exerciseId: e.id,
        name: e.name,
        sets: List.generate(defaultSetCount, (_) => const SetData()),
      );
    }).toList(),
  );
  ...
}

変換パターンの整理:

ネストした状態の更新: _withUpdatedSets

ActiveWorkoutState は3層のネスト構造を持つ:

ActiveWorkoutState
  ├── routineName: String
  ├── startedAt: DateTime
  └── exercises: List<ActiveExerciseData>
        ├── exerciseId: String
        ├── name: String
        └── sets: List<SetData>
              ├── weight: double
              ├── reps: int
              └── isPR: bool

「2番目の種目の1番目のセットの重量」を変えるには、3層すべてを新しく作り直す必要がある:

ActiveWorkoutState _withUpdatedSets(
  int exerciseIndex, List<SetData> newSets,
) {
  final currentState = state!;
  return currentState.copyWith(
    exercises: [
      for (var i = 0; i < currentState.exercises.length; i++)
        if (i == exerciseIndex)
          currentState.exercises[i].copyWith(sets: newSets)
        else
          currentState.exercises[i],
    ],
  );
}

keepAlive とセッションのライフサイクル

ActiveWorkoutNotifier は keepAlive: true で定義されている。セッションのライフサイクル全体:

1. アプリ起動
   └── build() → null (セッション未開始)

2. セッション開始
   └── startSession() → state = ActiveWorkoutState(...)

3. データ入力（画面遷移しても state 保持）
   ├── updateWeight() → state = state.copyWith(...)
   ├── updateReps() → state = state.copyWith(...)
   └── addSet() → state = state.copyWith(...)

4. セッション完了
   └── completeSession() → Repository に保存 → state = null

5. セッション破棄
   └── discardSession() → state = null

state = null で「セッション未開始」に戻る。keepAlive でもメモリリークしないのは、null に戻すことで実質データを解放しているため。

AsyncValue の3状態: loading / error / data

DB からデータを読むのは非同期処理。「読み込み中」「エラー」「成功」の3つの状態がある。

// FutureProvider は自動的に AsyncValue を返す
final routineListProvider = FutureProvider<List<RoutineWithExercises>>((ref) {
  final repo = ref.watch(routineRepositoryProvider);
  return repo.getAllRoutinesWithExercises();
});

この Provider を ref.watch すると、AsyncValue<List<RoutineWithExercises>> が返る。

.when() で3状態をハンドリング

Widget build(BuildContext context, WidgetRef ref) {
  final routineListAsync = ref.watch(routineListProvider);
  return Scaffold(
    body: ...
      routineListAsync.when(
        loading: () =>
            const Center(child: CircularProgressIndicator()),
        error: (error, _) => Center(
          child: Text('エラー: $error'),
        ),
        data: (routineList) => ListView.separated(
          itemCount: routineList.length + 1,
          itemBuilder: (context, index) { ... },
        ),
      ),
  );
}

.family: パラメータ付き Provider

「月ごとのトレーニング日」を取得する Provider を見てみよう:

final sessionDatesForMonthProvider =
    FutureProvider.family<List<DateTime>, ({int year, int month})>((
      ref,
      params,
    ) {
      ref.watch(allWorkoutsProvider);
      return ref
          .watch(historyRepositoryProvider)
          .getSessionDatesForMonth(params.year, params.month);
    });

使う側:

// 2026年3月のトレーニング日を取得
final dates = ref.watch(
  sessionDatesForMonthProvider((year: 2026, month: 3))
);
// 2026年4月のトレーニング日を取得（別のキャッシュ）
final nextDates = ref.watch(
  sessionDatesForMonthProvider((year: 2026, month: 4))
);

.family の判断基準:

Provider に渡すパラメータが必要?
  |
  +-- NO  --> 通常の Provider で十分
  |           例: routineListProvider（パラメータなし）
  |
  +-- YES --> .family を使う
              |
              同じパラメータで複数回呼ばれる?
              +-- YES --> キャッシュが効いて効率的
              |           例: sessionDatesForMonthProvider（同じ月は再取得不要）
              +-- NO  --> それでも .family は有効
                          例: lastSessionDateProvider(routineId)

.family のバリエーション

筋トレメモには3種類の .family Provider がある:

// 1. Record型パラメータ（複数値をまとめる）
FutureProvider.family<List<DateTime>, ({int year, int month})>

// 2. 単一パラメータ（DateTime）
FutureProvider.family<List<Workout>, DateTime>

// 3. 単一パラメータ（String）
FutureProvider.family<DateTime?, String>

// 4. 詳細取得（sessionId で引く）
FutureProvider.family<WorkoutDetail, String>

コード生成の限界: 手動定義が必要なケース

筋トレメモでは、一部の Provider を @riverpod ではなく手動で定義している:

/// drift 生成型を riverpod_generator で扱えないため手動で定義
final routineListProvider = FutureProvider<List<RoutineWithExercises>>((ref) {
  final repo = ref.watch(routineRepositoryProvider);
  return repo.getAllRoutinesWithExercises();
});

コメントに「drift 生成型を riverpod_generator で扱えないため手動で定義」と書かれている。

@riverpod で書けない場合:

• drift の生成型: RoutineWithExercises は drift が生成した型。riverpod_generator がこの型を解析できない
• DateTime 型のパラメータ: .family のパラメータに DateTime を使う場合、コード生成では型の等価性判定がうまく動かないことがある
• Record 型のパラメータ: ({int year, int month}) のような Record 型もコード生成が非対応

ProviderContainer: Provider の入れ物

通常のアプリでは ProviderScope が Widget ツリーのトップにある。テストでは ProviderContainer を直接作る:

container = ProviderContainer(
  overrides: [
    appDatabaseProvider.overrideWithValue(db),
    currentUserIdProvider.overrideWithValue(null),
  ],
);

override: テスト用にProviderを差し替える

テストで本番DBではなくインメモリDBを使う仕組み:

late AppDatabase db;
late ProviderContainer container;

setUp(() async {
  db = AppDatabase.forTesting(NativeDatabase.memory());
  container = ProviderContainer(
    overrides: [
      appDatabaseProvider.overrideWithValue(db),
      currentUserIdProvider.overrideWithValue(null),
    ],
  );
});

何が起きているか:

1. AppDatabase.forTesting(NativeDatabase.memory()) でインメモリDB(テスト後に消える)を作成
2. appDatabaseProvider.overrideWithValue(db) で、本番DBの代わりにインメモリDBを注入
3. WorkoutRepository も内部で ref.watch(appDatabaseProvider) しているので、自動的にインメモリDBを使う

setUp / tearDown: テストのライフサイクル

setUp(() async {
  db = AppDatabase.forTesting(NativeDatabase.memory());
  container = ProviderContainer(
    overrides: [
      appDatabaseProvider.overrideWithValue(db),
      currentUserIdProvider.overrideWithValue(null),
    ],
  );
  addTearDown(() async {
    container.dispose();
    await db.close();
  });
  notifier = container.read(activeWorkoutProvider.notifier);
});

テスト1回ごとのライフサイクル:

setUp
  ├── 1. インメモリDB作成
  ├── 2. Container作成（DBをoverride）
  └── 3. Notifier取得

テスト本体
  ├── notifier.startSession(...)
  ├── notifier.updateWeight(...)
  └── expect(...)

tearDown
  ├── 1. Container破棄（全Provider解放）
  └── 2. DB接続を閉じる

Repository = テスト容易性の鍵

テストが書きやすいのは、Repository パターンのおかげ。以下はDB操作のテスト:

setUp(() async {
  db = AppDatabase.forTesting(NativeDatabase.memory());
  repository = WorkoutRepository(db);
});

test('前回記録がない場合は空リストを返す', () async {
  final result = await repository.getLastSessionSets(exerciseId);
  expect(result, isEmpty);
});

Repository テストのポイント:

• Widget（UI）なしでロジックだけテストできる
• DB をインメモリに差し替えているので高速
• 「保存→取得→検証」のパターンで確実に動作を保証

// テストの典型パターン: 保存 → 取得 → 検証
await saveTestSession(       // 1. 保存
  exerciseId: exerciseId,
  exerciseName: 'ベンチプレス',
  sets: [SetData(weight: 60, reps: 10)],
);
final result = await repository.getLastSessionSets(exerciseId); // 2. 取得
expect(result.length, 1);    // 3. 検証
expect(result[0].weight, 60.0);

N+1 問題: getSessionDetail の落とし穴

筋トレメモの getSessionDetail にはパフォーマンスの改善余地がある:

Future<WorkoutDetail> getSessionDetail(String workoutId) async {
  // 1回目のクエリ: Workout を取得
  final workout = await (...).getSingle();

  // 2回目のクエリ: WorkoutExercises を取得
  final workoutExercises = await (...).get();

  // N回のクエリ: 各 Exercise の Sets を取得
  for (final ex in workoutExercises) {
    final sets = await (...).get();  // ここが N 回実行される!
    exercisesWithSets.add(...);
  }
}

N+1 問題とは:

• 1回のクエリで「種目リスト」を取得（1回目）
• 各種目ごとにループで「セット記録」を取得（N回）
• 合計 1 + N 回 のクエリが実行される

種目が3つなら 4回のクエリ。10種目なら 11回。種目数が増えるほど遅くなる。

改善案: JOIN で一括取得

// 改善版: 1回のクエリで全データを JOIN で取得
final rows = await (select(workoutExercises)
  .join([
    innerJoin(workoutSets,
      workoutSets.workoutExerciseId.equalsExp(workoutExercises.id)),
  ])
  ..where(workoutExercises.workoutId.equals(workoutId))
).get();
// → 1回のクエリで全データ取得。あとは Dart 側でグループ化

レイヤー設計のまとめ: 全体像

筋トレメモの全レイヤー構造を振り返ろう:

UI 層 (Flutter Widget)
  HomeScreen, WorkoutScreen, HistoryScreen
  ├── ref.watch で Provider を監視
  └── ref.read で Notifier のメソッドを呼ぶ
        |
Provider 層 (Riverpod)
  activeWorkoutProvider, routineListProvider, allWorkoutsProvider
  ├── Notifier: 状態管理 + ビジネスロジック
  └── FutureProvider / StreamProvider: 非同期データ供給
        |
Repository 層
  WorkoutRepository, HistoryRepository, RoutineRepository
  ├── ドメイン ↔ DB 形式の変換
  └── DB操作のカプセル化
        |
DB 層 (drift / SQLite)
  AppDatabase, テーブル定義, マイグレーション

各レイヤーの役割と、override によるテスト戦略: