flutter-data-layer
Flutter 프로젝트의 Data 레이어 패턴 — DataSource 인터페이스·구현, Repository, DTO와 도메인 모델 매핑, freezed 모델의 `fromJson`, 그리고 `rxdart`의 `BehaviorSubject`로 만드는 반응형 저장소. "DataSource 만들기", "Repository 구현", "리포지토리", "로컬/원격 데이터 소스", "BehaviorSubject", "스트림 저장소", "DTO 매핑", "fromJson" 같은 표현에 트리거합니다.
How do I install this agent skill?
npx skills add https://github.com/junsuk5/survival-flutter-skills --skill flutter-data-layerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural guidelines for Flutter's Data layer, including examples for Repositories, DataSources, and reactive state management. It promotes industry-standard patterns and includes common development commands for code generation. No malicious behavior or security vulnerabilities were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Flutter Data 레이어
에러 처리 연계
Data 레이어가 반환하는 타입은 flutter-error-handling 스킬에서 정의한 Result<D, E extends Error> 를 기반으로 한다. 플랫폼 예외는 Data 레이어에서 catch 해 typed error 로 변환한다. 자세한 규칙은 해당 스킬을 참고.
DataSource vs Repository
- DataSource: 단일 소스에 접근. 원격 API, 로컬 DB, 파일시스템, 클립보드 같은 단일 채널 하나만 다룬다. Data 레이어 대부분의 클래스가 여기 해당한다.
- Repository: 여러 DataSource를 조합해 도메인 관점으로 묶는다. 단일 소스만 쓰는데 굳이 "Repository" 이름을 붙이지 않는다.
이 프로젝트 기준:
// 단일 소스 → DataSource
abstract interface class RecipeDataSource {
Future<List<Map<String, dynamic>>> getRecipes();
}
// 도메인 관점의 접근 API → Repository
abstract interface class RecipeRepository {
Future<List<Recipe>> getRecipes();
Future<Recipe?> getRecipe(int id);
}
Repository 인터페이스는 도메인 타입(Recipe) 을 주고받지만, DataSource 인터페이스는 원시 타입/DTO(Map) 를 주고받는다는 점이 핵심이다. 매핑은 Repository 구현체가 담당한다.
도메인 계약 (lib/domain)
lib/domain/은 순수 Dart 레이어다.package:flutter/...import 금지.- 포함: 도메인 모델(
freezed), Repository 인터페이스, 에러 타입, UseCase. - ViewModel이 쓰는 모든 Repository는 이 레이어에 인터페이스가 있어야 한다 — Presentation 이 Data를 직접 참조하지 못하도록 보장하기 위함.
// lib/domain/repository/recipe_repository.dart
abstract interface class RecipeRepository {
Future<List<Recipe>> getRecipes();
Future<Recipe?> getRecipe(int id);
}
도메인 모델 (freezed)
모델은 항상 freezed + json_serializable 조합으로 만든다.
// lib/domain/model/recipe.dart
import 'package:freezed_annotation/freezed_annotation.dart';
import 'recipe_ingredient.dart';
part 'recipe.freezed.dart';
part 'recipe.g.dart';
@freezed
class Recipe with _$Recipe {
const factory Recipe({
required String category,
required int id,
required String name,
required String image,
required String chef,
required String time,
required double rating,
required List<RecipeIngredient> ingredients,
@Default(false) bool isFavorite,
}) = _Recipe;
factory Recipe.fromJson(Map<String, Object?> json) => _$RecipeFromJson(json);
}
파일 수정 후 반드시:
dart run build_runner build --delete-conflicting-outputs
DataSource 구현
원격
// lib/data/data_source/remote/remote_recipe_data_source_impl.dart
class RemoteRecipeDataSourceImpl implements RecipeDataSource {
@override
Future<List<Map<String, dynamic>>> getRecipes() async {
// http 호출 또는 mock
await Future.delayed(const Duration(microseconds: 500));
return _mockData['recipes']!;
}
}
로컬
// lib/data/data_source/local/default_local_storage.dart
class DefaultLocalStorage implements LocalStorage {
// SharedPreferences, sqflite 등으로 구현
}
명명 규칙 (이 프로젝트 기준):
- 인터페이스:
RecipeDataSource,LocalStorage— "무엇"을 나타내는 이름 - 구현:
RemoteRecipeDataSourceImpl,DefaultLocalStorage— "어디/어떻게"를 나타내는 이름 +Impl또는 기술명 접두어
Android 가이드라인과 다르게 이 프로젝트는 구현체에 Impl 접미어를 일관되게 사용하므로, 기존 컨벤션을 따른다.
Repository 구현
Repository 구현체는 DataSource 결과를 도메인 모델로 매핑한다. Map<String, dynamic> 같은 raw 타입은 여기서 끝나야 한다.
// lib/data/repository/mock_recipe_repository_impl.dart
class MockRecipeRepositoryImpl implements RecipeRepository {
final RecipeDataSource _recipeDataSource;
const MockRecipeRepositoryImpl({
required RecipeDataSource recipeDataSource,
}) : _recipeDataSource = recipeDataSource;
@override
Future<List<Recipe>> getRecipes() async {
final recipes = await _recipeDataSource.getRecipes();
return recipes.map(Recipe.fromJson).toList();
}
@override
Future<Recipe?> getRecipe(int id) async {
final recipes = await getRecipes();
return recipes.where((e) => e.id == id).firstOrNull;
}
}
핵심:
- 생성자에서 DataSource 를 주입받는다.
get_it이 이걸 해결한다. Repository인터페이스는domain에 있고, 구현은data에 있어 의존성 방향이 유지된다.- 매핑은
Recipe.fromJson같은 freezed 생성 팩토리를 이용한다. 별도 mapper 파일이 필요 없을 때가 많다.
반응형 저장소 — BehaviorSubject 패턴
이 프로젝트는 북마크처럼 여러 화면이 같은 상태를 관찰해야 할 때 rxdart 의 BehaviorSubject 를 쓴다. 최근 값이 있는 브로드캐스트 스트림이므로 새 구독자가 즉시 현재 상태를 받을 수 있다.
// lib/data/repository/mock_bookmark_repository_impl.dart
class MockBookmarkRepositoryImpl implements BookmarkRepository {
final _ids = <int>{2, 3};
final _controller = BehaviorSubject<Set<int>>();
MockBookmarkRepositoryImpl() {
_controller.add(_ids);
}
@override
Stream<Set<int>> bookmarkIdsStream() => _controller.stream;
@override
Future<void> toggle(int id) async {
if (_ids.contains(id)) {
_ids.remove(id);
} else {
_ids.add(id);
}
_controller.add(_ids);
}
}
언제 쓰나
- 저장/해제 같은 변이가 생긴 직후 다른 화면이 즉시 최신 상태를 봐야 할 때.
- 여러 feature가 동일한 데이터(북마크, 장바구니, 로그인 상태 등)를 공유해야 할 때.
언제 쓰지 말아야 하나
- 한 화면에서만 쓰고 재진입 시 다시 불러오면 충분한 데이터 → 그냥
Future반환.
UseCase 에서 BehaviorSubject 스트림과 일회성 Future 를 합성할 때:
// lib/domain/use_case/get_saved_recipes_use_case.dart
Stream<List<Recipe>> execute() async* {
final recipes = await _recipeRepository.getRecipes();
await for (final ids in _bookmarkRepository.bookmarkIdsStream()) {
yield recipes.where((e) => ids.contains(e.id)).toList();
}
}
이 패턴이 깔끔하다: Repository는 원자적 데이터(전체 목록, id 집합)만 책임지고, 유즈케이스가 그걸 화면 목적에 맞게 합성한다.
UseCase — Data와 Presentation 사이
UseCase는 "비즈니스 동작 하나"를 나타낸다. 이 프로젝트의 관례는:
- 위치:
lib/domain/use_case/<verb>_<noun>_use_case.dart - 단일 진입점
execute(...)하나만 공개 - 상태 없음 (field 는 주입받은 의존성뿐)
- 여러 Repository 를 조합하거나, 도메인 규칙(필터링/정렬)을 적용
- 반환 타입:
Future<T>,Future<Result<D, E>>, 또는Stream<T>
class GetSavedRecipesUseCase {
final RecipeRepository _recipeRepository;
final BookmarkRepository _bookmarkRepository;
const GetSavedRecipesUseCase({
required RecipeRepository recipeRepository,
required BookmarkRepository bookmarkRepository,
}) : _recipeRepository = recipeRepository,
_bookmarkRepository = bookmarkRepository;
Stream<List<Recipe>> execute() async* { ... }
}
ViewModel 은 Repository 를 직접 호출해도 되지만, 여러 소스를 섞거나 도메인 규칙이 끼어드는 순간 UseCase 로 분리한다.
체크리스트 — 새 DataSource / Repository 추가
-
lib/domain/model/<name>.dart— freezed 모델 -
lib/domain/repository/<name>_repository.dart—abstract interface class -
lib/data/data_source/{remote|local}/<name>_data_source_impl.dart— 실제 소스 접근 -
lib/data/repository/<name>_repository_impl.dart— DataSource 주입, 매핑, Repository 계약 구현 - 필요하면
BehaviorSubject로 스트림 노출 -
diSetup()에 인터페이스 타입으로 등록 -
dart run build_runner build --delete-conflicting-outputs
안티 패턴
- ❌ Repository 구현체가
Map<String, dynamic>을 호출자에게 노출 → 매핑은 Data 레이어 안에서 끝나야 한다. - ❌
domain/파일에package:flutter/material.dartimport → 순수성이 깨진다. - ❌ 구현 클래스 타입을 ViewModel/UseCase 에서 참조 → 인터페이스로 참조하라.
- ❌ UseCase 안에서
Repository가 해야 할 캐싱/저장을 대신 처리 → 책임이 흐려진다.
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-data-layer">View flutter-data-layer on skillZs</a>