Riverpod 3.0 정리 – 주요 변경사항과 사용법

Flutter에서 상태 관리를 담당하는 대표적인 라이브러리인 Riverpod이 3.0 버전으로 업데이트되면서 여러 기능 개선과 중요한 변화가 있었습니다. 이 글에서는 Riverpod 3.0의 주요 업데이트 내용을 요약하고, 실제 적용 시 주의할 점과 마이그레이션 팁을 정리합니다.

1. 새로운 기능

1.1 오프라인 퍼시스턴스(Persistence) – 실험적

Notifier 기반 프로바이더의 상태를 앱 종료 후에도 복원할 수 있도록 지원합니다. 예를 들어 사용자의 설정값이나 앱 상태를 SQLite 등 로컬 저장소에 저장하고, 앱 재실행 시 자동으로 불러올 수 있습니다.

@riverpod
class MyNotifier extends _$MyNotifier with Persisted {
  @override
  MyState build() {
    // 초기 상태 정의
  }
}

공식적으로 riverpod_sqflite 패키지를 통해 지원되며, 향후 다양한 저장소 연동이 가능해질 것으로 예상됩니다.

1.2 자동 재시도(Retry)

네트워크 요청 등 실패 가능성이 있는 FutureProvider, AsyncNotifier 등에서 기본적으로 지수 백오프 전략을 이용한 자동 재시도 기능이 적용됩니다.

전역 설정 예

ProviderScope(
  retry: (count, error) => Duration(seconds: 2 * count),
  child: MyApp(),
);

개별 프로바이더 설정 예:

@Riverpod(retry: (count, error) => null) // 재시도 비활성화
class MyProvider extends _$MyProvider { ... }

1.3 ref.mounted 지원

BuildContext.mounted와 유사하게, 프로바이더 내에서도 현재 Ref가 유효한지 확인할 수 있습니다. 비동기 작업 중 Ref가 dispose되었는지 체크할 때 유용합니다.

if (!ref.mounted) return;

1.4 pause/resume 기능

ref.listen()을 사용할 때, 조건에 따라 listen을 일시 중지하거나 재개할 수 있습니다. 예를 들어, 화면이 비활성화되었을 때 listener를 중지하고, 다시 활성화될 때 재개할 수 있습니다.

ref.listen(
  myProvider,
  (prev, next) {
    // 상태 변화 처리
  },
  pause: () => !TickerMode.of(context).enabled,
);

2. 테스트 지원 강화

2.1 테스트 컨테이너 개선

ProviderContainer.test()를 통해 테스트 환경에서 자동으로 dispose()를 처리할 수 있게 되었습니다.

test('테스트 예시', () {
  final container = ProviderContainer.test();
  // 테스트 코드 작성
});

2.2 override 개선

• NotifierProvider.overrideWithBuild를 통해 build 메서드만 목킹 가능
• FutureProvider, StreamProvider에서도 overrideWithValue를 다시 사용할 수 있음

2.3 위젯 테스트 시 ProviderContainer 접근

WidgetTester.container로 간편하게 테스트 중 ProviderContainer에 접근 가능합니다.

3. 주요 Breaking Changes

3.1 자동 재시도 기본 적용

기존에는 프로바이더가 실패 시 에러를 그대로 노출했지만, 이제 기본적으로 자동 재시도가 적용됩니다. 의도하지 않은 동작이 생기지 않도록 재시도 조건을 명시적으로 설정하는 것이 좋습니다.

@Riverpod(retry: (count, error) => null)
class MyProvider extends _$MyProvider { ... }

3.2 오프스크린 상태 자동 일시정지

TickerMode가 꺼져 있을 경우 프로바이더도 자동으로 pause 상태에 들어갑니다. 애니메이션이나 타이머 관련 로직이 중단될 수 있으므로 주의가 필요합니다.

3.3 legacy API 분리

기존에 사용하던 StateProvider, StateNotifierProvider, ChangeNotifierProvider 등은 legacy.dart로 분리되었으며, 새로운 프로젝트에서는 가능하면 최신 구조로 마이그레이션하는 것이 권장됩니다.

import 'package:riverpod/legacy.dart';

3.4 프로바이더 결과 비교 방식 통일

모든 프로바이더는 기본적으로 == 비교를 통해 상태 변경 여부를 감지하게 되었습니다. 불필요한 UI 리빌드가 줄어들 수 있으나, 복잡한 객체에서는 == 연산자 구현이 필요할 수 있습니다.

3.5 ProviderException

이제 프로바이더 내부에서 발생한 에러는 ProviderException으로 감싸져 전달됩니다. 실제 에러 객체는 exception 필드에서 접근할 수 있습니다.

try {
  await ref.read(myProvider.future);
} catch (e) {
  if (e is ProviderException) {
    print(e.exception); // 실제 에러
  }
}

4. 마이그레이션 팁

1. retry 전략을 명시적으로 설정하거나 비활성화하세요.
2. Ticker 기반 애니메이션/타이머 사용 시 TickerMode 제어 여부 확인이 필요합니다.
3. 기존 StateProvider 등은 legacy.dart로 이동되었으며, 가능하면 최신 구조로 전환하세요.
4. 테스트 코드에서 새로운 테스트 도구를 적극 활용해보세요.
5. 오프라인 저장 기능이나 pause/resume은 성능 최적화와 UX 개선에 활용할 수 있습니다.

마무리

Riverpod 3.0은 이전 버전에 비해 더 유연하고 안정적인 상태 관리 체계를 제공합니다. 특히 상태 복원, 자동 재시도, 테스트 강화 등은 실제 프로젝트에서 큰 도움이 될 수 있는 기능입니다. 다만 breaking changes도 많기 때문에, 프로젝트에 적용하기 전에 변경사항을 충분히 이해하고 테스트하는 것이 필요합니다.

오늘도 즐코 빡코 !!