flutter-error-handling

Original：🇺🇸 English

Translated

Flutter 프로젝트의 타입 안전 에러 처리 패턴 — `Error` 마커 인터페이스, freezed 기반 `Result<D, E>` sealed 클래스, 기능별 에러 enum, `switch` 패턴 매칭으로 성공/실패를 처리하는 방법. "Result 래퍼", "에러 처리", "ResultSuccess", "ResultError", "NetworkError", "타입 안전 에러", "freezed sealed", "exception 대신 Result" 같은 표현에 트리거합니다.

2installs

Sourcejunsuk5/survival-flutter-skills

Added on2026-05-17

NPX Install

npx skill4agent add junsuk5/survival-flutter-skills flutter-error-handling

SKILL.md Content

View Translation Comparison →

Flutter 에러 처리 — Result<D, E>

핵심 철학

예상 가능한 실패에는 예외를 던지지 않는다. 대신 타입으로 표현된

Result

를 반환한다. 이렇게 하면 호출자가 실패 케이스를 타입 시스템으로 강제로 다루게 되어, 런타임에 놓치는 UI 에러 경로가 사라진다.

예외는 프레임워크/플랫폼이 던진 것을 가장 낮은 레이어(Data)에서 잡아

Result.error(...)

로 변환하는 용도로만 쓴다. UseCase, ViewModel, Screen 은 더 이상 try/catch 를 보지 않는다.

기반 타입 (

lib/core/domain/error/

)

Error 마커 인터페이스

dart

// lib/core/domain/error/error.dart
abstract interface class Error {}

모든 커스텀 에러 타입은 이

Error

를 구현한다.

Result

의

는 반드시

extends Error

이므로 Dart 표준

Exception

과 섞이지 않는다.

Result<D, E>

dart

// lib/core/domain/error/result.dart
import 'package:freezed_annotation/freezed_annotation.dart';
import 'error.dart';

part 'result.freezed.dart';

@freezed
sealed class Result<D, E extends Error> with _$Result<D, E> {
  const factory Result.success(D data) = ResultSuccess;
  const factory Result.error(E error) = ResultError;
}

중요:

sealed

로 선언했기 때문에

switch

에서 모든 케이스를 Dart 컴파일러가 강제한다. 케이스를 빠뜨리면 컴파일 경고가 뜬다.

기능별 에러 정의

에러는 enum +
implements Error
로 정의한다. 각 값은 사용자에게 보여줄 한국어 메시지를

toString()

에 둔다.

dart

// lib/core/domain/error/network_error.dart
enum NetworkError implements Error {
  requestTimeout,
  noInternet,
  serverError,
  unknown;

  @override
  String toString() => switch (this) {
        NetworkError.requestTimeout => '요청 시간이 초과되었습니다',
        NetworkError.noInternet => '인터넷 연결을 확인해 주세요',
        NetworkError.serverError => '서버에 문제가 발생했습니다',
        NetworkError.unknown => '알 수 없는 문제가 발생했습니다',
      };
}

공유 에러(

NetworkError

)는

lib/core/domain/error/

에, feature 전용 에러는

lib/domain/error/<feature>_error.dart

에 둔다. 예:

BookmarkError

,

NewRecipeError

.

다중 에러는 표현하지 않는다. 한

Result

는 정확히 한 가지 에러만 담는다. 여러 조건을 동시에 알려줘야 한다면 그것은 도메인 설계 문제다.

UseCase / Repository 반환 타입

dart

// UseCase 시그니처
Future<Result<List<String>, NetworkError>> execute();
Future<Result<List<Recipe>, BookmarkError>> execute(int recipeId);

성공 데이터 타입
```
D
```
와 에러 타입
```
E
```
를 명시한다.
Data 레이어에서 네트워크/DB 예외를 catch 해
```
NetworkError.unknown
```
같은 값으로 변환한다.
UseCase는 여러 Repository 에러를 자기 feature 에러로 매핑해서 반환한다 (예: 북마크 저장 실패 시
```
BookmarkError.saveFailed
```
).

ViewModel에서 소비하기

sealed 타입이므로 타입 파라미터를 명시해

switch

에서 패턴 매칭한다. 이 프로젝트는 다음 형태를 정석으로 쓴다 (

home_view_model.dart

참조).

dart

void _fetchCategories() async {
  final result = await _getCategoriesUseCase.execute();

  switch (result) {
    case ResultSuccess<List<String>, NetworkError>():
      _state = state.copyWith(
        categories: result.data,
        selectedCategory: 'All',
      );
      notifyListeners();

    case ResultError<List<String>, NetworkError>():
      switch (result.error) {
        case NetworkError.requestTimeout:
        case NetworkError.noInternet:
        case NetworkError.serverError:
        case NetworkError.unknown:
          _eventController.add(result.error);
      }
  }
}

왜 이렇게 쓰나:

```
ResultSuccess<D, E>()
```
/
```
ResultError<D, E>()
```
를 적어야 제네릭이 유지되고
```
result.data
```
/
```
result.error
```
의 구체 타입이 살아 있다.
안쪽
```
switch (result.error)
```
는 모든 enum 케이스를 강제로 나열하게 만들어, 새 에러가 추가될 때 누락된 처리 지점을 컴파일러가 알려준다.

에러를 UI로 전달하는 방식

두 가지 표준 패턴이 있다.

1) 한 번 보여주는 스낵바/토스트 —

StreamController

이벤트

dart

final _eventController = StreamController<NetworkError>();
Stream<NetworkError> get eventStream => _eventController.stream;

Root 위젯이

eventStream

을 listen 해서

ScaffoldMessenger.showSnackBar

를 호출한다. 상태에 담으면 리빌드마다 반복되므로 이벤트로 내보낸다.

2) 지속 상태(에러 배너) — State 필드

에러 화면 자체를 그려야 한다면

State

에

NetworkError? error

필드를 두고

copyWith(error: ...)

로 반영한다. 사용자가 닫거나 재시도하면

error: null

로 초기화한다.

Data 레이어 — 예외를 Result로 바꾸는 지점

dart

Future<Result<List<RecipeDto>, NetworkError>> getRecipes() async {
  try {
    final raw = await _recipeDataSource.getRecipes();
    return Result.success(raw.map(RecipeDto.fromJson).toList());
  } on SocketException {
    return const Result.error(NetworkError.noInternet);
  } on TimeoutException {
    return const Result.error(NetworkError.requestTimeout);
  } catch (_) {
    return const Result.error(NetworkError.unknown);
  }
}

원칙:

예외가 발생하는 레이어가 곧 잡는 레이어다. 플랫폼/HTTP 예외는 Data에서, 도메인 검증 실패는 Domain에서
```
Result.error
```
로 변환한다.
Presentation 에는 예외가 절대 올라오지 않게 한다. ViewModel 의
```
try/catch
```
가 보이면 경고 신호다.

어떤 에러 타입을 쓸지 결정표

시나리오	에러 타입	위치
네트워크 호출 실패	`NetworkError`	`core/domain/error/`
로컬 저장소/DB 실패	`LocalError` (필요시 신규)	`core/domain/error/`
기능 전용 실패 (북마크 저장 실패 등)	`BookmarkError` 같은 enum	`lib/domain/error/`
여러 DataSource 를 묶는 Repository	상위 에러 타입 ( `NetworkError` 또는 feature error)	해당 feature

체크리스트

새 feature의 실패 유형을 enum +
implements Error
로 정의했다
UseCase 시그니처가
```
Future<Result<D, FooError>>
```
로 타입 파라미터를 명시한다

ViewModel에서

switch (result)

가

ResultSuccess<D, E>()

/

ResultError<D, E>()

를 모두 처리한다

에러 enum 의 모든 값이 내부
```
switch (result.error)
```
에서 나열되어 있다
Data 레이어가 플랫폼 예외를 catch 해
```
Result.error
```
로 변환한다
Presentation 어디에도
```
try/catch
```
가 떠돌지 않는다

안티 패턴

❌
```
Future<List<Recipe>>
```
를 그대로 반환하고 실패를
```
throw
```
로 전달 → 호출자가 실패를 잊는다.
❌
```
Result<List<Recipe>, Exception>
```
처럼
```
Exception
```
을 에러 타입으로 사용 →
```
Error
```
마커의 의미가 사라진다.
❌ 한
```
Result
```
에 리스트로 여러 에러를 담기 → 모델이 복잡해지고 UI 분기가 폭발한다.
❌
```
switch
```
에서
```
default:
```
로 퉁치기 → 새 에러 값 추가 시 컴파일러가 경고해 주는 안전망을 날려버린다.

flutter-error-handling

NPX Install

Tags

SKILL.md Content

Flutter 에러 처리 — Result<D, E>

핵심 철학

기반 타입 (
`lib/core/domain/error/`
)

Error 마커 인터페이스

Result<D, E>

기능별 에러 정의

UseCase / Repository 반환 타입

ViewModel에서 소비하기

에러를 UI로 전달하는 방식

1) 한 번 보여주는 스낵바/토스트 —
`StreamController`
이벤트

2) 지속 상태(에러 배너) — State 필드

Data 레이어 — 예외를 Result로 바꾸는 지점

어떤 에러 타입을 쓸지 결정표

체크리스트

안티 패턴

flutter-error-handling

NPX Install

Tags

SKILL.md Content

Flutter 에러 처리 — Result<D, E>

핵심 철학

기반 타입 (lib/core/domain/error/)

Error 마커 인터페이스

Result<D, E>

기능별 에러 정의

UseCase / Repository 반환 타입

ViewModel에서 소비하기

에러를 UI로 전달하는 방식

1) 한 번 보여주는 스낵바/토스트 — StreamController 이벤트

2) 지속 상태(에러 배너) — State 필드

Data 레이어 — 예외를 Result로 바꾸는 지점

어떤 에러 타입을 쓸지 결정표

체크리스트

안티 패턴

기반 타입 (
`lib/core/domain/error/`
)

1) 한 번 보여주는 스낵바/토스트 —
`StreamController`
이벤트