지난 글에서 FutureBuilder와 AsyncValue로 로딩, 데이터, 에러를 나눠 그리는 법을 봤다. 그런데 에러를 어디서 어떻게 다룰지는 아직 정하지 않았다. 사용자 목록을 불러오는 함수를 흔히 이렇게 쓰게 된다. 앱이 죽는 게 싫어서 try/catch로 감싸고, 실패하면 빈 목록을 돌려준다.

Future<List<User>> fetchUsers() async {
  try {
    final response = await dio.get('/users');
    final list = response.data as List;
    return list.map((e) => User.fromJson(e as Map<String, dynamic>)).toList();
  } catch (e) {
    print(e); // 콘솔에만 찍고
    return [];  // 빈 목록으로 대신함
  }
}

앱은 죽지 않는다. 그런데 비행기 모드에서 이 화면을 열면 "목록이 비어 있습니다"가 뜬다. 사용자는 데이터가 정말 없는 건지, 인터넷이 끊긴 건지 알 수 없다. 다시 불러올 방법도 없다.

원인: 실패와 빈 결과를 같은 것으로 표현했다

catch에서 에러를 삼키고 []를 돌려주면, 화면에는 "실패"와 "데이터 없음"이 똑같은 모습으로 나온다. 에러를 UI까지 전달하지 못하니 화면이 할 수 있는 게 없다. 에러는 잡아서 숨기는 게 아니라, 화면이 알아볼 수 있는 상태로 전달해야 한다.

해결 1: 에러를 그대로 던지고, 화면에서 네 가지 상태로 나눈다

데이터를 가져오는 쪽에서는 try/catch를 빼고 에러가 그대로 올라가게 둔다. Riverpod의 FutureProvider는 던져진 에러를 AsyncValue의 에러 상태로 받아준다.

final usersProvider = FutureProvider<List<User>>((ref) async {
  final response = await dio.get('/users');
  final list = response.data as List;
  return list.map((e) => User.fromJson(e as Map<String, dynamic>)).toList();
});

화면은 네 가지 상태를 모두 그린다. 지난 글의 로딩, 데이터, 에러에 "데이터가 비어 있음"이 추가된다.

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

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final users = ref.watch(usersProvider);

    return users.when(
      loading: () => const Center(child: CircularProgressIndicator()),
      error: (e, _) => ErrorView(
        message: errorMessage(e),
        onRetry: () => ref.invalidate(usersProvider),
      ),
      data: (list) {
        if (list.isEmpty) {
          return const Center(child: Text('아직 사용자가 없어요')); // 진짜 빈 경우
        }
        return ListView.builder(
          itemCount: list.length,
          itemBuilder: (context, i) => ListTile(title: Text(list[i].name)),
        );
      },
    );
  }
}

이제 "데이터 없음"은 data 안의 isEmpty로만 나타나고, 실패는 error로 나뉜다. 두 경우가 섞이지 않는다.

에러 화면에는 이유와 다시 시도 버튼을 넣는다

class ErrorView extends StatelessWidget {
  final String message;
  final VoidCallback onRetry;

  const ErrorView({super.key, required this.message, required this.onRetry});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(message),
          const SizedBox(height: 12),
          ElevatedButton(onPressed: onRetry, child: const Text('다시 시도')),
        ],
      ),
    );
  }
}

VoidCallback은 함수 글에서 본 () -> Unit에 해당하는 콜백 타입이다. 다시 시도를 누르면 ref.invalidate(usersProvider)가 불려서 요청을 새로 보낸다. 한 번 만든 ErrorView는 앱의 어느 화면에서든 재사용한다.

사용자에게 e.toString()을 그대로 보여주지 않는다

Text('에러: $e')로 예외를 그대로 보여주면 DioException [connection error]: ... 같은 긴 문장이 나온다. 에러의 종류를 보고 사용자가 이해할 문구로 바꿔주는 함수를 한 곳에 만든다.

String errorMessage(Object error) {
  if (error is DioException) {
    return switch (error.type) {
      DioExceptionType.connectionTimeout ||
      DioExceptionType.receiveTimeout =>
        '응답이 너무 늦어요. 잠시 후 다시 시도해 주세요',
      DioExceptionType.connectionError => '인터넷 연결을 확인해 주세요',
      DioExceptionType.badResponse =>
        '서버에 문제가 있어요 (${error.response?.statusCode})',
      _ => '알 수 없는 오류가 났어요',
    };
  }
  return '알 수 없는 오류가 났어요';
}

HTTP 통신 글에서 본 e.type이 여기서 쓰인다. error is DioException은 "이 에러가 dio가 던진 것인가"를 확인하는 is 검사이고, 그 안에서는 error를 DioException으로 바로 쓸 수 있다.

당겨서 새로고침: RefreshIndicator

RefreshIndicator(
  onRefresh: () async {
    ref.invalidate(usersProvider);
    await ref.read(usersProvider.future); // 새 데이터가 올 때까지 기다림
  },
  child: ListView.builder(
    physics: const AlwaysScrollableScrollPhysics(), // 항목이 적어도 당겨지게
    itemCount: list.length,
    itemBuilder: (context, i) => ListTile(title: Text(list[i].name)),
  ),
)

onRefresh가 Future를 돌려주는 동안 동그라미가 돈다. 그리고 한 가지 함정이 있다. 항목이 화면보다 적어서 목록이 스크롤되지 않으면 당겨도 새로고침이 안 된다. AlwaysScrollableScrollPhysics를 달아서 항상 당겨지게 해야 한다. RefreshIndicator의 child는 스크롤되는 위젯이어야 한다.

화면 전체가 아니라 일부분이 실패했을 때: SnackBar

목록 불러오기가 실패하면 화면 전체를 에러로 바꾸지만, 버튼을 눌러 저장하는 동작이 실패했을 때는 화면을 바꾸지 않고 잠깐 알림만 띄운다.

ElevatedButton(
  onPressed: () async {
    try {
      await saveUser();
    } catch (e) {
      if (!context.mounted) return; // 기다리는 동안 화면이 사라졌을 수 있음
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('저장에 실패했어요')),
      );
    }
  },
  child: const Text('저장'),
)

await 뒤에서 context를 쓰기 전에 context.mounted를 확인한다. 서버 응답을 기다리는 동안 사용자가 뒤로 가기를 눌러서 이 화면이 이미 사라졌을 수 있고, 사라진 화면의 context로 스낵바를 띄우면 에러가 난다. 에디터도 이런 코드에 "비동기 구간 건너 BuildContext를 쓰지 말라"는 경고를 띄운다.

• 목록처럼 화면의 내용 자체를 못 가져왔다면: 화면 전체 에러 + 다시 시도 버튼
• 저장, 삭제처럼 동작 하나가 실패했다면: 화면은 그대로 두고 SnackBar

마지막 안전망: 어디서도 잡지 못한 에러

try/catch와 AsyncValue로 다룬 에러 말고, 예상 못 한 에러가 앱을 죽이거나 빨간 화면을 띄울 수 있다. Flutter는 이런 에러를 한곳에서 받는 자리를 두 개 준다.

import 'dart:ui'; // PlatformDispatcher

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Flutter가 잡은 에러(위젯을 그리다 난 에러 등)
  FlutterError.onError = (details) {
    FlutterError.presentError(details); // 기본 동작 유지
    // 여기서 오류 수집 서비스로 보낸다
  };

  // Flutter 콜백 밖에서 난 에러(비동기, 플랫폼 호출 등)
  PlatformDispatcher.instance.onError = (error, stack) {
    // 여기서도 오류 수집 서비스로 보낸다
    return true; // 처리했다고 알림
  };

  runApp(const MyApp());
}

• FlutterError.onError: 프레임워크가 잡은 모든 에러가 모이는 곳이다. 기본값은 에러를 기기 로그에 출력한다
• PlatformDispatcher.instance.onError: Flutter 콜백 안에서 난 게 아닌 에러가 모이는 곳이다. Future 안에서 잡히지 않은 예외 등이 여기로 온다

이 두 곳에 크래시 리포트 서비스를 연결하면 사용자 기기에서 난 에러를 내가 받아볼 수 있다. 위젯을 그리다 실패했을 때 보이는 에러 화면도 바꿀 수 있다.

ErrorWidget.builder = (details) {
  return const Scaffold(
    body: Center(child: Text('문제가 생겼어요. 앱을 다시 실행해 주세요')),
  );
};

기본값은 개발 중에는 빨간 에러 화면이 뜨는데, 사용자에게는 이렇게 읽을 수 있는 문구를 보여주는 게 낫다.

Compose, SwiftUI와 비교하면

// Compose - UiState + Snackbar
when (val s = state) {
    is UiState.Loading -> CircularProgressIndicator()
    is UiState.Error -> ErrorView(s.message, onRetry = viewModel::retry)
    is UiState.Success -> if (s.items.isEmpty()) EmptyView() else ItemList(s.items)
}
scope.launch { snackbarHostState.showSnackbar("저장에 실패했어요") }

// SwiftUI - enum 상태 + alert
switch state {
case .loading: ProgressView()
case .error(let message): ErrorView(message: message, retry: load)
case .loaded(let items): items.isEmpty ? AnyView(EmptyView()) : AnyView(ItemList(items))
}
.alert("저장에 실패했어요", isPresented: $showAlert) { Button("확인") {} }

• 네 가지 상태 나누기: Flutter AsyncValue.when + isEmpty / Compose sealed UiState와 when / SwiftUI enum과 switch
• 가벼운 알림: Flutter SnackBar / Compose SnackbarHost / SwiftUI .alert나 토스트 직접 구현
• 새로고침: Flutter RefreshIndicator / Compose PullToRefreshBox / SwiftUI .refreshable
• 비동기 후 화면 확인: Flutter context.mounted / Compose는 코루틴 취소가 자동 / SwiftUI Task가 뷰 수명에 묶임
• 전역 에러: Flutter FlutterError.onError, PlatformDispatcher.instance.onError / 안드로이드 UncaughtExceptionHandler / iOS는 크래시 리포터 연동

세 곳 모두 상태를 로딩, 에러, 빈 화면, 데이터로 나눠 그리는 발상은 같다. Flutter만의 특징은 await 뒤에 context.mounted를 직접 확인해야 한다는 점이다.

정리

• catch에서 에러를 삼키고 빈 목록을 돌려주면 "실패"와 "데이터 없음"이 구분되지 않으므로, 에러를 던져서 화면까지 전달한다
• 화면은 로딩, 에러, 빈 결과, 데이터 네 가지를 모두 그리고, 에러 화면에는 이유와 다시 시도 버튼을 넣는다
• e.toString()을 그대로 보이지 않고, 에러 종류(DioExceptionType)에 따라 사용자 문구로 바꾸는 함수를 한곳에 둔다
• RefreshIndicator는 스크롤 위젯이 필요하고, 항목이 적을 때도 당겨지려면 AlwaysScrollableScrollPhysics를 단다
• 화면 전체를 못 가져왔으면 에러 화면, 동작 하나가 실패했으면 SnackBar를 쓰고, await 뒤에서는 context.mounted를 먼저 확인한다
• 예상 못 한 에러는 FlutterError.onError와 PlatformDispatcher.instance.onError에서 한곳으로 모아 오류 수집 서비스에 보낸다

다음 글부터는 5단계로 넘어가서, 앱이 커졌을 때 파일을 어떻게 나눌지, 폴더 구조(Feature-first와 Layer-first)를 다뤄보겠다.