flutter-bloc-development

仓库: abdelhakrazi/flutter-bloc-clean-architecture-skill
安装量: 106
排名: #7965

安装

npx skills add https://github.com/abdelhakrazi/flutter-bloc-clean-architecture-skill --skill flutter-bloc-development

Flutter BLoC Development

This skill enforces BLoC state management, strict layer separation, and mandatory use of design system constants for all Flutter development in this codebase.

Decision Tree: Choosing Your Approach User task → What are they building? │ ├─ New screen/feature → Full stack implementation: │ 1. Define BLoC (events, states, bloc) │ 2. Create/update data layer (repository, datasource) │ 3. Build UI with design system │ ├─ New widget only → Presentation layer: │ 1. Create in widgets/ (reusable) or screens/ (feature-specific) │ 2. Use design system constants (NO hardcoded values) │ 3. Connect to existing BLoC if needed │ ├─ Data integration → Data layer only: │ 1. Create datasource (Supabase/Firebase SDK calls) │ 2. Create repository (maps to domain entities) │ 3. Wire up in existing or new BLoC │ └─ Refactoring → Identify violations: 1. Check for hardcoded colors/spacing/typography 2. Check for business logic in UI 3. Check for direct SDK calls outside datasources 4. Check for missing Loading state before async operations 5. Check for missing Equatable on Events/States 6. Check for improper error handling (use SnackBar + AppColors.error)

Architecture at a Glance lib/ ├── bloc/[feature]/ # Events, States, BLoC ├── data/datasources/ # Backend SDK calls (Supabase, Firebase) ├── data/repositories/ # Data orchestration, maps to entities ├── data/models/ # DTOs, JSON serialization ├── domain/entities/ # Pure Dart business objects ├── screens/ # Feature screens ├── widgets/ # Reusable components └── utils/ # Design system (colors, spacing, typography)

Key Rules:

All state changes flow through BLoC No direct backend SDK calls outside datasources Zero hardcoded values (colors, spacing, typography) Repository pattern for all data access BLoC Implementation Event → State → BLoC (Three Files Per Feature)

Events — User actions and system triggers:

abstract class FeatureEvent extends Equatable { const FeatureEvent(); @override List get props => []; }

class FeatureActionRequested extends FeatureEvent { final String param; const FeatureActionRequested({required this.param}); @override List get props => [param]; }

States — All possible UI states:

abstract class FeatureState extends Equatable { const FeatureState(); @override List get props => []; }

class FeatureInitial extends FeatureState {} class FeatureLoading extends FeatureState {}

class FeatureSuccess extends FeatureState { final DataType data; const FeatureSuccess(this.data); @override List get props => [data]; }

class FeatureError extends FeatureState { final String message; const FeatureError(this.message); @override List get props => [message]; }

BLoC — Event handlers with Loading → Success/Error pattern:

class FeatureBloc extends Bloc { final FeatureRepository _repository;

FeatureBloc({required FeatureRepository repository}) : _repository = repository, super(FeatureInitial()) { on(_onActionRequested); }

Future _onActionRequested( FeatureActionRequested event, Emitter emit, ) async { emit(FeatureLoading()); try { final result = await _repository.doSomething(event.param); emit(FeatureSuccess(result)); } catch (e) { emit(FeatureError(e.toString())); } } }

CRITICAL: Always emit Loading before async work, then Success or Error. Never skip the loading state.

Data Layer

Data Flow:

UI Event → BLoC (emit Loading) → Repository → Datasource (SDK) ↓ Response → Repository (map to entity) → BLoC (emit Success/Error) → UI

Datasource — Backend SDK calls only:

class FeatureDataSource { final SupabaseClient _supabase; FeatureDataSource(this._supabase);

Future> fetch() async { return await _supabase.from('table').select().single(); } }

Repository — Orchestration and mapping:

class FeatureRepository { final FeatureDataSource _dataSource; FeatureRepository(this._dataSource);

Future fetchData() async { final response = await _dataSource.fetch(); return DomainEntity.fromJson(response); } }

Design System (Non-Negotiable) Colors

✅ AppColors.primary, AppColors.error, AppColors.textPrimary ❌ Color(0xFF...), Colors.blue, inline hex values

Spacing

✅ AppSpacing.xs (4), AppSpacing.sm (8), AppSpacing.md (16), AppSpacing.lg (24), AppSpacing.xl (32) ✅ AppSpacing.screenHorizontal (24), AppSpacing.screenVertical (16) ❌ EdgeInsets.all(16.0), hardcoded padding values

Border Radius

✅ AppRadius.sm (8), AppRadius.md (12), AppRadius.lg (16), AppRadius.xl (24) ❌ BorderRadius.circular(12), inline radius values

Typography

✅ AppTypography.headlineLarge, AppTypography.bodyMedium, theme.textTheme.bodyMedium ❌ TextStyle(fontSize: 16), inline text styles

UI Patterns Screen Template GradientScaffold( body: SafeArea( child: Column( children: [ Padding( padding: const EdgeInsets.all(AppSpacing.screenHorizontal), child: HeaderWidget(), ), Expanded( child: SingleChildScrollView( padding: const EdgeInsets.symmetric(horizontal: AppSpacing.screenHorizontal), child: ContentWidget(), ), ), Padding( padding: const EdgeInsets.all(AppSpacing.screenHorizontal), child: ActionButton( onPressed: () => context.read().add(ActionEvent()), ), ), ], ), ), )

BLoC Consumer Pattern BlocConsumer( listener: (context, state) { if (state is FeatureError) { ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(state.message), backgroundColor: AppColors.error), ); } }, builder: (context, state) { if (state is FeatureLoading) return const Center(child: CircularProgressIndicator()); if (state is FeatureSuccess) return SuccessWidget(data: state.data); return const SizedBox.shrink(); }, )

Common Pitfalls

❌ Business logic in widgets → Move to BLoC ❌ Direct Supabase/Firebase calls in repository → Move to datasource ❌ Skipping loading state before async operations → Always emit Loading first ❌ Hardcoded colors like Color(0xFF4A90A4) → Use AppColors.primary ❌ Magic numbers like padding: 16 → Use AppSpacing.md

Quick Reference Action Pattern Dispatch event context.read().add(Event()) Watch state inline context.watch().state Listen + Build BlocConsumer Listen only BlocListener Build only BlocBuilder Checklist Before Submitting Events/States/BLoC use Equatable All async: Loading → Success/Error No business logic in UI No SDK calls outside datasources Zero hardcoded colors/spacing/typography Error handling shows SnackBar with AppColors.error Code formatted with dart format

← 返回排行榜