flutter-error-handling
Flutter 프로젝트의 타입 안전 에러 처리 패턴 — `Error` 마커 인터페이스, freezed 기반 `Result<D, E>` sealed 클래스, 기능별 에러 enum, `switch` 패턴 매칭으로 성공/실패를 처리하는 방법. "Result 래퍼", "에러 처리", "ResultSuccess", "ResultError", "NetworkError", "타입 안전 에러", "freezed sealed", "exception 대신 Result" 같은 표현에 트리거합니다.
How do I install this agent skill?
npx skills add https://github.com/junsuk5/survival-flutter-skills --skill flutter-error-handlingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a secure architectural guide for implementing type-safe error handling in Flutter applications using the Result pattern and the freezed code generation library. It contains only documentation and implementation examples with no security risks detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Flutter 에러 처리 — Result<D, E>
핵심 철학
예상 가능한 실패에는 예외를 던지지 않는다. 대신 타입으로 표현된 Result 를 반환한다. 이렇게 하면 호출자가 실패 케이스를 타입 시스템으로 강제로 다루게 되어, 런타임에 놓치는 UI 에러 경로가 사라진다.
예외는 프레임워크/플랫폼이 던진 것을 가장 낮은 레이어(Data)에서 잡아 Result.error(...) 로 변환하는 용도로만 쓴다. UseCase, ViewModel, Screen 은 더 이상 try/catch 를 보지 않는다.
기반 타입 (lib/core/domain/error/)
Error 마커 인터페이스
// lib/core/domain/error/error.dart
abstract interface class Error {}
모든 커스텀 에러 타입은 이 Error 를 구현한다. Result 의 E 는 반드시 extends Error 이므로 Dart 표준 Exception 과 섞이지 않는다.
Result<D, E>
// 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() 에 둔다.
// 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 반환 타입
// 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 참조).
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 이벤트
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로 바꾸는 지점
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:로 퉁치기 → 새 에러 값 추가 시 컴파일러가 경고해 주는 안전망을 날려버린다.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/junsuk5/survival-flutter-skills/flutter-error-handling">View flutter-error-handling on skillZs</a>