ProviderScope와 오버라이드 완벽 가이드

Flutter Riverpod에서 ProviderScope의 역할과 Provider 오버라이드 기법을 초급 개발자도 쉽게 이해할 수 있도록 설명합니다. 테스트 환경 구축부터 중첩 스코프 활용까지 실무에서 꼭 필요한 내용을 담았습니다.

---

목차

1. ProviderScope의_역할
2. ProviderContainer_이해하기
3. Provider_오버라이드
4. 테스트에서_오버라이드_활용
5. 중첩_ProviderScope
6. UncontrolledProviderScope

---

1. ProviderScope의 역할

입사 첫 주, 김개발 씨는 Flutter 프로젝트를 처음 열어보았습니다. main.dart 파일 맨 위에서 낯선 위젯을 발견했습니다.

ProviderScope라는 이름의 이 위젯이 앱 전체를 감싸고 있었는데, 대체 왜 이렇게 해야 하는 걸까요?

ProviderScope는 Riverpod에서 모든 Provider가 살아 숨 쉬는 공간을 만들어주는 위젯입니다. 마치 물고기가 살려면 어항이 필요하듯, Provider들이 제대로 작동하려면 ProviderScope라는 어항이 필요합니다.

이 위젯 없이는 어떤 Provider도 사용할 수 없습니다.

다음 코드를 살펴봅시다.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

// 간단한 카운터 Provider 정의
final counterProvider = StateProvider<int>((ref) => 0);

void main() {
  // ProviderScope로 앱 전체를 감싸줍니다
  runApp(
    const ProviderScope(
      child: MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(home: HomeScreen());
  }
}

김개발 씨는 입사 첫 주를 맞이했습니다. 설레는 마음으로 회사의 Flutter 프로젝트를 처음 열어본 그는 main.dart 파일에서 이상한 위젯을 발견했습니다.

ProviderScope라는 이름의 위젯이 앱 전체를 꽁꽁 감싸고 있었습니다. "이건 대체 뭐지?" 김개발 씨가 혼잣말을 하자, 옆자리의 박시니어 씨가 슬쩍 모니터를 들여다보았습니다.

"아, ProviderScope? Riverpod 쓰려면 필수야.

이거 없으면 아무것도 안 돼." 그렇다면 ProviderScope가 정확히 무슨 일을 하는 걸까요? 쉽게 비유하자면, ProviderScope는 마치 대형 쇼핑몰의 물류 창고와 같습니다.

쇼핑몰의 모든 매장에서 물건을 팔려면 어딘가에 재고가 보관되어 있어야 합니다. ProviderScope가 바로 그 역할을 합니다.

앱에서 사용하는 모든 Provider의 상태를 저장하고 관리하는 중앙 창고인 셈입니다. Riverpod 이전에 사용되던 Provider 패키지에서는 위젯 트리의 특정 위치에 Provider를 배치해야 했습니다.

트리 구조를 신경 쓰며 어디에 무엇을 놓을지 고민해야 했죠. 실수로 잘못된 위치에 놓으면 "Provider를 찾을 수 없습니다"라는 에러가 튀어나왔습니다.

Riverpod은 이런 문제를 해결하기 위해 ProviderScope라는 개념을 도입했습니다. 앱의 최상위에 딱 한 번만 배치하면 그 아래 어디서든 모든 Provider에 접근할 수 있습니다.

위젯 트리 구조를 신경 쓸 필요가 없어진 것입니다. 위의 코드를 살펴보겠습니다.

main 함수에서 runApp을 호출할 때 ProviderScope로 MyApp을 감싸고 있습니다. 이 한 줄이 앱 전체에서 Riverpod을 사용할 수 있게 해주는 마법의 주문입니다.

ProviderScope 내부에서는 ProviderContainer라는 객체가 생성됩니다. 이 컨테이너가 실제로 모든 Provider의 상태를 저장하고 관리합니다.

ProviderScope는 이 컨테이너를 위젯 트리 전체에 공유하는 역할을 합니다. 실무에서는 어떨까요?

거의 모든 Riverpod 프로젝트에서 main.dart 파일은 동일한 패턴을 따릅니다. ProviderScope가 최상위에 있고, 그 안에 MaterialApp이나 CupertinoApp이 들어갑니다.

이것이 Riverpod의 표준 구조입니다. 주의할 점이 있습니다.

ProviderScope를 빠뜨리면 앱이 실행되자마자 크래시가 발생합니다. "Bad state: No ProviderScope found"라는 에러 메시지를 보게 될 것입니다.

초보 개발자들이 가장 많이 겪는 실수 중 하나입니다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, 그러니까 물고기를 키우려면 어항부터 준비해야 하는 거네요!" 박시니어 씨가 미소를 지었습니다. "정확해.

그리고 이 어항이 있어야 나중에 물을 바꾸거나 장식을 추가하는 것처럼 다양한 조작도 할 수 있어."

실전 팁

💡 - main.dart에서 ProviderScope를 최상위에 배치하는 것을 팀 컨벤션으로 정하세요

• ProviderScope를 빠뜨리면 런타임 에러가 발생하니 프로젝트 시작 시 가장 먼저 설정하세요

---

2. ProviderContainer 이해하기

김개발 씨는 ProviderScope에 대해 배웠지만, 문득 궁금해졌습니다. "실제로 Provider의 상태는 어디에 저장되는 거지?" 박시니어 씨가 흰 종이를 꺼내 그림을 그리기 시작했습니다.

"ProviderContainer에 대해 알아야 할 때가 됐군."

ProviderContainer는 Provider의 상태를 실제로 저장하고 관리하는 핵심 객체입니다. ProviderScope가 겉으로 보이는 위젯이라면, ProviderContainer는 그 뒤에서 일하는 실세입니다.

마치 레스토랑의 주방장처럼 보이지 않는 곳에서 모든 것을 총괄합니다.

다음 코드를 살펴봅시다.

import 'package:flutter_riverpod/flutter_riverpod.dart';

final greetingProvider = Provider<String>((ref) => '안녕하세요!');

void main() {
  // ProviderContainer를 직접 생성합니다
  final container = ProviderContainer();

  // container를 통해 Provider 값을 읽을 수 있습니다
  final greeting = container.read(greetingProvider);
  print(greeting); // 출력: 안녕하세요!

  // 사용이 끝나면 반드시 dispose 해줍니다
  container.dispose();
}

김개발 씨는 ProviderScope를 배운 뒤 조금 더 깊이 파고들고 싶었습니다. "ProviderScope가 감싸주는 건 알겠는데, 실제로 데이터는 어디에 저장되는 거예요?" 박시니어 씨가 화이트보드에 그림을 그리기 시작했습니다.

"ProviderScope는 사실 껍데기야. 진짜 일은 ProviderContainer가 해." ProviderContainer를 이해하려면 도서관을 떠올려 보면 됩니다.

도서관 건물이 ProviderScope라면, 그 안의 서가와 도서 관리 시스템이 ProviderContainer입니다. 건물은 사람들이 드나드는 공간을 제공하지만, 실제로 책을 분류하고 관리하는 것은 내부 시스템입니다.

ProviderContainer는 세 가지 핵심 역할을 수행합니다. 첫째, 모든 Provider의 현재 상태를 메모리에 저장합니다.

둘째, Provider 간의 의존성을 추적합니다. 셋째, Provider가 더 이상 필요 없을 때 자동으로 정리합니다.

흥미로운 점은 ProviderContainer를 Flutter 위젯 없이도 사용할 수 있다는 것입니다. 위의 코드 예제처럼 순수한 Dart 코드에서도 Provider를 활용할 수 있습니다.

이 특성 덕분에 단위 테스트가 훨씬 쉬워집니다. 코드를 자세히 살펴보겠습니다.

ProviderContainer()를 호출하면 새로운 컨테이너가 생성됩니다. 이 컨테이너의 read 메서드를 사용하면 Provider의 현재 값을 읽을 수 있습니다.

Flutter의 context나 ref 없이도 가능합니다. 하지만 주의해야 할 점이 있습니다.

직접 생성한 ProviderContainer는 반드시 dispose를 호출해서 정리해야 합니다. 그렇지 않으면 메모리 누수가 발생할 수 있습니다.

ProviderScope를 사용하면 위젯이 제거될 때 자동으로 처리되지만, 직접 생성한 경우는 개발자가 책임져야 합니다. 실무에서 ProviderContainer를 직접 다루는 경우는 주로 두 가지입니다.

테스트 코드를 작성할 때와 Flutter 외부에서 Riverpod을 사용할 때입니다. 일반적인 앱 개발에서는 ProviderScope가 알아서 ProviderContainer를 관리해주므로 직접 건드릴 일이 거의 없습니다.

김개발 씨가 물었습니다. "그러면 ProviderScope 안에 ProviderContainer가 숨어 있는 거네요?" 박시니어 씨가 고개를 끄덕였습니다.

"맞아. ProviderScope의 소스 코드를 열어보면 내부에서 ProviderContainer를 생성하고 관리하는 걸 볼 수 있어.

우리는 그냥 ProviderScope만 잘 배치하면 나머지는 알아서 돌아가는 거지."

실전 팁

💡 - 일반적인 Flutter 앱 개발에서는 ProviderContainer를 직접 다룰 필요가 없습니다

• 테스트나 CLI 도구 개발 시에는 ProviderContainer를 직접 생성해서 사용하세요

---

3. Provider 오버라이드

어느 날 김개발 씨는 API 서버가 점검 중이라 개발을 진행할 수 없는 상황에 놓였습니다. "서버 없이 개발할 방법이 없을까요?" 박시니어 씨가 웃으며 말했습니다.

"Provider 오버라이드를 사용하면 돼. 실제 서버 대신 가짜 데이터로 바꿔치기할 수 있거든."

Provider 오버라이드는 원래 정의된 Provider의 값을 다른 값으로 대체하는 기능입니다. 마치 영화 촬영에서 실제 배우 대신 스턴트맨을 투입하는 것과 같습니다.

겉으로 보기엔 같은 역할을 하지만 내부 구현은 완전히 다릅니다.

다음 코드를 살펴봅시다.

import 'package:flutter_riverpod/flutter_riverpod.dart';

// 실제 API를 호출하는 Repository
abstract class UserRepository {
  Future<String> fetchUserName();
}

class RealUserRepository implements UserRepository {
  @override
  Future<String> fetchUserName() async {
    // 실제로는 API 호출
    return '서버에서 가져온 이름';
  }
}

// 테스트용 가짜 Repository
class FakeUserRepository implements UserRepository {
  @override
  Future<String> fetchUserName() async {
    return '테스트 사용자';
  }
}

final userRepositoryProvider = Provider<UserRepository>(
  (ref) => RealUserRepository(),
);

// 오버라이드 적용
void main() {
  runApp(
    ProviderScope(
      overrides: [
        userRepositoryProvider.overrideWithValue(FakeUserRepository()),
      ],
      child: const MyApp(),
    ),
  );
}

금요일 오후, 김개발 씨는 난감한 상황에 처했습니다. 백엔드 팀에서 서버 점검을 한다고 공지했는데, 마감은 월요일이었습니다.

API 없이 어떻게 프론트엔드 개발을 진행할 수 있을까요? 박시니어 씨가 김개발 씨의 어깨를 툭 쳤습니다.

"Provider 오버라이드 써봤어?" 김개발 씨가 고개를 저었습니다. "그게 뭐예요?" Provider 오버라이드를 이해하려면 연극 무대를 상상해 보세요.

주연 배우가 갑자기 아프면 대역이 무대에 올라갑니다. 관객 입장에서는 같은 역할을 하는 사람이지만, 실제로는 다른 사람입니다.

Provider 오버라이드도 마찬가지입니다. 같은 Provider 이름을 사용하지만 내부 구현을 완전히 다른 것으로 바꿔치기합니다.

이 기능이 왜 필요할까요? 실제 개발 현장에서는 다양한 상황이 발생합니다.

서버가 아직 준비되지 않았거나, 특정 시나리오를 테스트하고 싶거나, 외부 서비스 연동 없이 빠르게 UI를 개발하고 싶을 때가 있습니다. 이럴 때 오버라이드가 구원투수로 등장합니다.

코드를 살펴보겠습니다. 먼저 UserRepository라는 추상 클래스를 정의했습니다.

실제 구현체인 RealUserRepository는 API를 호출하고, 가짜 구현체인 FakeUserRepository는 하드코딩된 값을 반환합니다. 핵심은 ProviderScope의 overrides 파라미터입니다.

이 배열에 오버라이드할 Provider와 대체할 값을 지정합니다. userRepositoryProvider.overrideWithValue(FakeUserRepository())라고 작성하면, 앱 전체에서 userRepositoryProvider를 사용할 때 FakeUserRepository가 반환됩니다.

오버라이드에는 여러 방식이 있습니다. overrideWithValue는 이미 생성된 객체로 대체할 때 사용합니다.

overrideWith는 새로운 생성 로직을 제공할 때 사용합니다. 상황에 맞게 선택하면 됩니다.

실무에서 가장 많이 활용되는 케이스는 환경별 설정입니다. 개발 환경에서는 로컬 서버를, 스테이징 환경에서는 테스트 서버를, 프로덕션에서는 실제 서버를 사용하도록 오버라이드할 수 있습니다.

코드 한 줄 바꾸지 않고 환경에 따라 동작을 변경할 수 있습니다. 주의할 점이 있습니다.

오버라이드된 Provider는 해당 ProviderScope 내에서만 유효합니다. 상위 스코프에서는 원래 값이 그대로 사용됩니다.

이 특성을 이해하지 못하면 "분명히 오버라이드했는데 왜 안 바뀌지?"라며 머리를 쥐어뜯게 됩니다. 월요일 아침, 김개발 씨는 당당하게 결과물을 보여주었습니다.

서버 없이도 모든 화면이 완성되어 있었습니다. "오버라이드 덕분에 가짜 데이터로 개발할 수 있었어요!" 박시니어 씨가 엄지를 치켜세웠습니다.

실전 팁

💡 - 추상 클래스나 인터페이스를 정의하고 구현체를 주입하는 패턴을 사용하면 오버라이드가 쉬워집니다

• 환경 변수에 따라 자동으로 오버라이드를 적용하는 유틸리티 함수를 만들어두면 편리합니다

---

4. 테스트에서 오버라이드 활용

코드 리뷰 시간, 박시니어 씨가 김개발 씨의 PR을 보며 말했습니다. "기능은 잘 작동하는데, 테스트 코드가 없네?" 김개발 씨가 머뭇거렸습니다.

"API를 호출하는 코드라서 테스트하기가 어려워요..." 박시니어 씨가 고개를 저었습니다. "오버라이드를 쓰면 쉽게 테스트할 수 있어."

테스트에서 Provider 오버라이드는 외부 의존성을 제거하고 예측 가능한 환경을 만드는 핵심 도구입니다. 실제 API, 데이터베이스, 외부 서비스 없이도 비즈니스 로직을 철저히 검증할 수 있습니다.

마치 비행기 조종사가 실제 비행 전에 시뮬레이터로 훈련하는 것과 같습니다.

다음 코드를 살펴봅시다.

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_test/flutter_test.dart';

// Provider 정의
final authProvider = StateNotifierProvider<AuthNotifier, AuthState>(
  (ref) => AuthNotifier(),
);

class AuthNotifier extends StateNotifier<AuthState> {
  AuthNotifier() : super(const AuthState.initial());

  Future<void> login(String email, String password) async {
    state = const AuthState.loading();
    // 실제로는 API 호출
    state = const AuthState.authenticated(userId: '123');
  }
}

// 테스트 코드
void main() {
  test('로그인 성공 시 인증 상태로 변경된다', () async {
    // 테스트용 ProviderContainer 생성
    final container = ProviderContainer();
    addTearDown(container.dispose);

    // AuthNotifier 가져오기
    final authNotifier = container.read(authProvider.notifier);

    // 로그인 실행
    await authNotifier.login('test@test.com', 'password');

    // 상태 검증
    final state = container.read(authProvider);
    expect(state, isA<AuthStateAuthenticated>());
  });
}

김개발 씨는 처음으로 테스트 코드를 작성해보려 했습니다. 하지만 막상 시작하려니 막막했습니다.

로그인 기능을 테스트하려면 실제 서버에 요청을 보내야 하나요? 네트워크 상태에 따라 테스트가 실패하면 어쩌죠?

박시니어 씨가 옆에 앉아 설명을 시작했습니다. "좋은 테스트의 핵심은 격리야.

테스트하려는 코드만 테스트하고, 나머지는 통제된 환경으로 만들어야 해." 테스트에서 Provider 오버라이드를 사용하는 것은 마치 과학 실험과 같습니다. 과학자들이 한 번에 하나의 변수만 바꿔가며 실험하듯, 우리도 테스트할 부분만 실제로 동작시키고 나머지는 고정된 값으로 대체합니다.

위 코드에서 주목할 부분은 ProviderContainer를 직접 생성한다는 것입니다. Flutter 위젯 없이도 Provider를 테스트할 수 있습니다.

이것이 Riverpod의 강력한 장점 중 하나입니다. addTearDown(container.dispose)는 테스트가 끝난 후 정리 작업을 예약합니다.

이렇게 하면 각 테스트가 독립적으로 실행되어 서로 영향을 주지 않습니다. 만약 API 호출을 완전히 제거하고 싶다면 어떻게 할까요?

바로 오버라이드를 사용합니다. 테스트 전용 Mock 객체를 만들고, ProviderContainer 생성 시 오버라이드를 적용하면 됩니다.

더 복잡한 예를 살펴보겠습니다. HTTP 클라이언트를 오버라이드하면 네트워크 요청 자체를 가로챌 수 있습니다.

성공 응답, 실패 응답, 타임아웃 등 다양한 시나리오를 테스트할 수 있습니다. 실제 네트워크 없이도 말입니다.

위젯 테스트에서도 마찬가지입니다. ProviderScope의 overrides에 테스트용 Provider를 넣으면, 해당 테스트에서는 가짜 데이터가 사용됩니다.

UI가 다양한 상태에서 올바르게 렌더링되는지 검증할 수 있습니다. 실무에서 자주 오버라이드하는 Provider들이 있습니다.

HTTP 클라이언트, 로컬 스토리지, 현재 시간을 반환하는 Provider, 사용자 인증 상태 등입니다. 이런 외부 의존성을 추상화하고 Provider로 관리하면 테스트가 훨씬 수월해집니다.

주의할 점은 오버라이드에 너무 의존하지 않는 것입니다. 모든 것을 가짜로 대체하면 실제 환경에서 발생하는 버그를 놓칠 수 있습니다.

단위 테스트에서는 오버라이드를 적극 활용하되, 통합 테스트에서는 실제 구현을 사용하는 균형이 필요합니다. 김개발 씨는 테스트 코드를 완성하고 PR을 다시 올렸습니다.

박시니어 씨가 Approve를 누르며 말했습니다. "이제야 제대로 된 코드네.

테스트가 있으니까 나중에 리팩토링해도 안심이야."

실전 팁

💡 - 각 테스트마다 새로운 ProviderContainer를 생성하여 테스트 간 격리를 보장하세요

• 자주 사용하는 Mock 객체들은 별도 파일로 분리해서 재사용하세요

---

5. 중첩 ProviderScope

어느 날 김개발 씨는 특이한 요구사항을 받았습니다. "이 화면에서만 다른 테마를 적용해주세요." 앱 전체 테마는 그대로 유지하면서 특정 화면만 다르게?

어떻게 해야 할지 막막했습니다. 박시니어 씨가 힌트를 주었습니다.

"ProviderScope를 중첩해서 써봐."

중첩 ProviderScope는 특정 위젯 트리 영역에서만 Provider를 오버라이드하는 기법입니다. 마치 건물 안에 작은 방을 만드는 것과 같습니다.

방 안에서는 다른 규칙이 적용되지만, 방 밖은 여전히 건물의 규칙을 따릅니다.

다음 코드를 살펴봅시다.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

final themeColorProvider = Provider<Color>((ref) => Colors.blue);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Column(
          children: [
            // 기본 테마 사용 (파란색)
            const NormalSection(),

            // 중첩 스코프로 테마 오버라이드 (빨간색)
            ProviderScope(
              overrides: [
                themeColorProvider.overrideWithValue(Colors.red),
              ],
              child: const SpecialSection(),
            ),
          ],
        ),
      ),
    );
  }
}

class NormalSection extends ConsumerWidget {
  const NormalSection({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final color = ref.watch(themeColorProvider);
    return Container(color: color, height: 100); // 파란색
  }
}

class SpecialSection extends ConsumerWidget {
  const SpecialSection({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final color = ref.watch(themeColorProvider);
    return Container(color: color, height: 100); // 빨간색
  }
}

김개발 씨는 디자이너로부터 재미있는 요청을 받았습니다. "앱 전체는 파란색 테마인데, 이벤트 페이지만 빨간색으로 해주세요." 처음에는 별도의 상태를 만들어서 조건문으로 처리하려 했습니다.

하지만 코드가 지저분해질 것 같았습니다. 박시니어 씨에게 조언을 구하자, 의외로 간단한 답이 돌아왔습니다.

"ProviderScope를 중첩해서 써. 그 안에서만 테마를 오버라이드하면 돼." 중첩 ProviderScope를 이해하려면 러시아 인형 마트료시카를 떠올려 보세요.

큰 인형 안에 작은 인형이 들어 있듯, ProviderScope 안에 또 다른 ProviderScope를 넣을 수 있습니다. 작은 인형은 큰 인형의 특성을 물려받지만, 자기만의 특성도 가질 수 있습니다.

위 코드를 살펴보겠습니다. 앱 최상위에는 기본 ProviderScope가 있습니다.

여기서 themeColorProvider는 파란색을 반환합니다. NormalSection은 이 기본값을 그대로 사용합니다.

SpecialSection은 다릅니다. 이 위젯을 감싸는 중첩된 ProviderScope가 있고, 여기서 themeColorProvider를 빨간색으로 오버라이드합니다.

따라서 SpecialSection 내부에서는 같은 Provider를 읽어도 빨간색이 반환됩니다. 핵심은 범위의 제한입니다.

오버라이드된 값은 해당 ProviderScope 내부에서만 유효합니다. 스코프 밖으로 나가면 원래 값이 적용됩니다.

이것이 중첩 스코프의 강력한 점입니다. 실무에서 중첩 ProviderScope는 다양하게 활용됩니다.

멀티 테넌트 앱에서 각 테넌트별로 다른 설정을 적용할 때, 특정 화면에서만 다른 API 엔드포인트를 사용할 때, A/B 테스트를 구현할 때 유용합니다. 또 다른 활용 예는 위젯 테스트입니다.

특정 위젯만 테스트할 때 필요한 Provider만 오버라이드하는 최소한의 스코프를 만들 수 있습니다. 불필요한 의존성을 줄이고 테스트를 더 빠르게 실행할 수 있습니다.

주의할 점도 있습니다. 중첩 스코프를 남발하면 코드를 이해하기 어려워집니다.

"이 Provider의 값이 어디서 오는 거지?" 디버깅할 때 혼란스러워질 수 있습니다. 꼭 필요한 경우에만 사용하세요.

또한 중첩된 ProviderScope에서 새로운 상태가 생성된다는 점을 기억해야 합니다. 오버라이드된 StateProvider는 상위 스코프의 상태와 별개입니다.

상태를 공유해야 한다면 다른 접근 방식이 필요합니다. 김개발 씨는 이벤트 페이지를 ProviderScope로 감싸고 테마 Provider를 오버라이드했습니다.

코드 한 줄 추가로 원하는 결과를 얻었습니다. 디자이너도, 김개발 씨도 모두 만족했습니다.

실전 팁

💡 - 중첩 스코프는 꼭 필요한 경우에만 사용하고, 팀 내에서 사용 기준을 정해두세요

• 디버깅을 위해 어떤 Provider가 어느 스코프에서 오버라이드되는지 문서화하세요

---

6. UncontrolledProviderScope

김개발 씨는 회사의 레거시 프로젝트를 Riverpod으로 마이그레이션하는 임무를 맡았습니다. 문제는 기존에 이미 ProviderContainer를 직접 관리하는 코드가 있다는 것이었습니다.

어떻게 하면 기존 코드를 유지하면서 Riverpod 위젯을 사용할 수 있을까요?

UncontrolledProviderScope는 외부에서 생성한 ProviderContainer를 위젯 트리에 연결하는 특수한 위젯입니다. 일반 ProviderScope가 자체적으로 컨테이너를 생성하고 관리하는 반면, UncontrolledProviderScope는 이미 존재하는 컨테이너를 그대로 사용합니다.

마치 자동차를 새로 사는 대신 렌트하는 것과 같습니다.

다음 코드를 살펴봅시다.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

final counterProvider = StateProvider<int>((ref) => 0);

// 앱 시작 전에 컨테이너를 미리 생성
late final ProviderContainer globalContainer;

Future<void> main() async {
  // 앱 초기화 단계에서 컨테이너 생성
  globalContainer = ProviderContainer();

  // 초기 데이터 로드 등의 작업 수행
  await _initializeApp(globalContainer);

  runApp(
    // 미리 생성한 컨테이너를 사용
    UncontrolledProviderScope(
      container: globalContainer,
      child: const MyApp(),
    ),
  );
}

Future<void> _initializeApp(ProviderContainer container) async {
  // 앱 시작 전 필요한 초기화 작업
  // 예: 저장된 사용자 세션 복원
  final savedCount = await _loadSavedCount();
  container.read(counterProvider.notifier).state = savedCount;
}

Future<int> _loadSavedCount() async {
  // 실제로는 SharedPreferences 등에서 로드
  return 42;
}

김개발 씨는 난감한 상황에 처했습니다. 회사의 레거시 프로젝트에는 이미 복잡한 초기화 로직이 있었습니다.

앱이 시작되기 전에 여러 데이터를 미리 로드하고, 그 결과에 따라 초기 상태를 설정해야 했습니다. 일반 ProviderScope로는 이런 요구사항을 충족하기 어려웠습니다.

박시니어 씨가 해결책을 제시했습니다. "UncontrolledProviderScope를 써봐.

컨테이너를 네가 직접 관리할 수 있어." UncontrolledProviderScope를 이해하려면 호텔과 개인 주택의 차이를 생각해 보세요. 일반 ProviderScope는 호텔과 같습니다.

체크인하면 방이 준비되어 있고, 체크아웃하면 정리됩니다. 반면 UncontrolledProviderScope는 개인 주택입니다.

이미 가구가 배치된 내 집을 그대로 사용합니다. 이 위젯이 필요한 상황은 크게 세 가지입니다.

첫째, 앱 시작 전에 Provider 상태를 미리 설정해야 할 때입니다. 둘째, Flutter 외부 코드와 ProviderContainer를 공유해야 할 때입니다.

셋째, 테스트에서 특정 컨테이너를 위젯에 주입해야 할 때입니다. 위 코드를 살펴보겠습니다.

main 함수에서 globalContainer를 먼저 생성합니다. 그 다음 _initializeApp에서 필요한 초기화 작업을 수행합니다.

이때 컨테이너의 Provider에 직접 접근해서 초기값을 설정할 수 있습니다. runApp을 호출할 때 UncontrolledProviderScope의 container 파라미터에 미리 생성한 컨테이너를 전달합니다.

이제 위젯 트리 전체에서 이 컨테이너를 사용하게 됩니다. 중요한 차이점이 있습니다.

일반 ProviderScope는 위젯이 제거될 때 자동으로 컨테이너를 dispose합니다. 하지만 UncontrolledProviderScope는 그렇지 않습니다.

컨테이너의 생명주기를 개발자가 직접 관리해야 합니다. 앱이 종료될 때 dispose를 호출해야 메모리 누수를 방지할 수 있습니다.

실무에서 이 패턴은 주로 복잡한 앱 초기화가 필요할 때 사용됩니다. 예를 들어 Firebase 초기화, 사용자 인증 상태 복원, 로컬 데이터베이스 연결 등을 앱 시작 전에 완료해야 하는 경우입니다.

스플래시 화면을 보여주는 동안 이런 작업을 수행하고, 완료되면 메인 화면으로 전환합니다. 주의할 점은 이 방식이 Riverpod의 권장 패턴은 아니라는 것입니다.

대부분의 경우 일반 ProviderScope와 FutureProvider 조합으로 충분합니다. UncontrolledProviderScope는 특수한 상황에서만 사용하세요.

김개발 씨는 UncontrolledProviderScope를 사용해 레거시 초기화 로직과 새로운 Riverpod 코드를 성공적으로 통합했습니다. "이렇게 유연하게 사용할 수 있다니, Riverpod 정말 잘 만들었네요." 박시니어 씨가 웃으며 말했습니다.

"그래서 내가 추천한 거야."

실전 팁

💡 - UncontrolledProviderScope를 사용할 때는 반드시 컨테이너의 dispose를 직접 처리하세요

• 특별한 이유가 없다면 일반 ProviderScope를 사용하는 것이 권장됩니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!