Padrões Dart/Flutter

Quando Usar

Use esta habilidade quando:

• Iniciar um novo recurso Flutter e precisar de padrões idiomáticos para gerenciamento de estado, navegação ou acesso a dados
• Revisar ou escrever código Dart e precisar de orientação sobre segurança contra nulos (null safety), tipos selados (sealed types) ou composição assíncrona (async composition)
• Configurar um novo projeto Flutter e escolher entre BLoC, Riverpod ou Provider
• Implementar clientes HTTP seguros, integração WebView ou armazenamento local
• Escrever testes para widgets Flutter, Cubits ou provedores Riverpod
• Conectar GoRouter com guardas de autenticação

Como Funciona

Esta habilidade fornece padrões de código Dart/Flutter prontos para copiar e colar, organizados por preocupação:

1. Segurança contra nulos (Null safety) — evite !, prefira ?./??/correspondência de padrões (pattern matching)
2. Estado imutável — classes seladas (sealed classes), freezed, copyWith
3. Composição assíncrona (Async composition) — Future.wait concorrente, BuildContext seguro após await
4. Arquitetura de Widgets — extrair para classes (não métodos), propagação de const, reconstruções com escopo (scoped rebuilds)
5. Gerenciamento de estado — eventos BLoC/Cubit, notifiers Riverpod e provedores derivados
6. Navegação — GoRouter com guardas de autenticação reativos via refreshListenable
7. Rede (Networking) — Dio com interceptores, atualização de token com guarda de retentativa única (one-time retry guard)
8. Tratamento de erros — captura global, ErrorWidget.builder, conexão com crashlytics
9. Testes — unidade (teste BLoC), widget (substituições de ProviderScope), fakes em vez de mocks

Exemplos

// Sealed state — prevents impossible states
sealed class AsyncState<T> {}
final class Loading<T> extends AsyncState<T> {}
final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }
final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }

// GoRouter with reactive auth redirect
final router = GoRouter(
  refreshListenable: GoRouterRefreshStream(authCubit.stream),
  redirect: (context, state) {
    final authed = context.read<AuthCubit>().state is AuthAuthenticated;
    if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';
    return null;
  },
  routes: [...],
);

// Riverpod derived provider with safe firstWhereOrNull
@riverpod
double cartTotal(Ref ref) {
  final cart = ref.watch(cartNotifierProvider);
  final products = ref.watch(productsProvider).valueOrNull ?? [];
  return cart.fold(0.0, (total, item) {
    final product = products.firstWhereOrNull((p) => p.id == item.productId);
    return total + (product?.price ?? 0) * item.quantity;
  });
}

Padrões práticos e prontos para produção para aplicações Dart e Flutter. Independentes de bibliotecas sempre que possível, com cobertura explícita dos pacotes mais comuns do ecossistema.

1. Fundamentos de Segurança Contra Nulos (Null Safety)

Prefira Padrões em Vez do Operador Bang (!)

// BAD — crashes at runtime if null
final name = user!.name;

// GOOD — provide fallback
final name = user?.name ?? 'Unknown';

// GOOD — Dart 3 pattern matching (preferred for complex cases)
final display = switch (user) {
  User(:final name, :final email) => '$name <$email>',
  null => 'Guest',
};

// GOOD — guard early return
String getUserName(User? user) {
  if (user == null) return 'Unknown';
  return user.name; // promoted to non-null after check
}

Evite o Uso Excessivo de late

// BAD — defers null error to runtime
late String userId;

// GOOD — nullable with explicit initialization
String? userId;

// OK — use late only when initialization is guaranteed before first access
// (e.g., in initState() before any widget interaction)
late final AnimationController _controller;

@override
void initState() {
  super.initState();
  _controller = AnimationController(vsync: this, duration: const Duration(milliseconds: 300));
}

2. Estado Imutável

Classes Seladas (Sealed Classes) para Hierarquias de Estado

sealed class UserState {}

final class UserInitial extends UserState {}

final class UserLoading extends UserState {}

final class UserLoaded extends UserState {
  const UserLoaded(this.user);
  final User user;
}

final class UserError extends UserState {
  const UserError(this.message);
  final String message;
}

// Exhaustive switch — compiler enforces all branches
Widget buildFrom(UserState state) => switch (state) {
  UserInitial() => const SizedBox.shrink(),
  UserLoading() => const CircularProgressIndicator(),
  UserLoaded(:final user) => UserCard(user: user),
  UserError(:final message) => ErrorText(message),
};

Freezed para Imutabilidade Sem Código Repetitivo (Boilerplate-Free)

…