Como implementar Riverpod em apps com regras complexas: guia prático para produção

Aplicativos Flutter com regras de elegibilidade, permissões, cálculos, integrações e fluxos assíncronos exigem mais do que atualizar a tela quando um botão é pressionado. Eles precisam de uma estrutura que mantenha decisões importantes previsíveis, testáveis e fáceis de evoluir.

Neste guia, você verá como implementar Riverpod em Flutter para separar interface, estado, dependências e regras de negócio. O foco é uma abordagem prática para produção, em que o Riverpod atua como composição e orquestração — não como depósito de toda a lógica do aplicativo.

Quando Riverpod é a escolha certa para apps Flutter complexos

O Riverpod se torna especialmente útil quando o estado deixa de ser apenas local à tela. Se uma ação depende de dados remotos, perfil do usuário, permissões, validações, cache e regras compartilhadas, concentrar tudo em widgets rapidamente cria acoplamento e comportamentos difíceis de prever.

Alguns sinais comuns são: widgets com muitas chamadas de serviço, múltiplos booleanos como isLoading e hasError, dependência excessiva de BuildContext, regras repetidas entre telas e dificuldade para testar um fluxo sem renderizar a interface.

Em um aplicativo de crédito, por exemplo, a elegibilidade pode depender de score, documentação, valor solicitado, limite disponível e retorno de APIs. A tela deve apresentar o resultado; a regra que decide se a proposta pode avançar deve existir fora dela.

O Riverpod ajuda porque os providers são declarativos, podem compor dependências e não dependem diretamente do contexto da árvore de widgets. Isso favorece um gerenciamento de estado Flutter mais previsível, inclusive em módulos grandes.

Defina a fronteira entre interface, estado e regras de negócio

Antes de criar providers, defina responsabilidades. Essa decisão evita o erro de transformar um notifier em uma classe enorme que valida formulário, chama API, calcula valores, mapeia erros e controla navegação ao mesmo tempo.

Uma divisão prática é:

• Widgets: exibem estado e enviam intenções do usuário.
• Notifiers: coordenam ações, observam dependências e fazem transições de estado.
• Casos de uso: concentram decisões de domínio e regras reutilizáveis.
• Repositórios: definem contratos para acesso a dados.
• Fontes de dados: implementam comunicação com API, banco local ou SDK externo.

No checkout, o controller pode receber a intenção de confirmar a compra. Um caso de uso então valida cupom, estoque, frete e condição de pagamento; o repositório consulta os serviços necessários. Dessa forma, a arquitetura Flutter escalável preserva uma fronteira clara entre apresentação e domínio.

abstract interface class ConfirmOrderUseCase {
  Future<OrderResult> call(CheckoutInput input);
}

final confirmOrderUseCaseProvider = Provider<ConfirmOrderUseCase>((ref) {
  return ConfirmOrderUseCaseImpl(ref.watch(orderRepositoryProvider));
});

Modele estados imutáveis que representam o fluxo de negócio

Estados pouco claros produzem interfaces pouco claras. Em vez de combinar flags soltas, como isLoading, isApproved, hasDocumentsPending e hasError, modele fases que o processo realmente pode assumir.

Uma solicitação pode estar em edição, validação, envio, pendência documental, aprovação, recusa ou falha recuperável. Esses estados são mutuamente compreensíveis e facilitam a cobertura de testes.

sealed class ProposalState {
  const ProposalState();
}

class ProposalEditing extends ProposalState {
  const ProposalEditing(this.draft);
  final ProposalDraft draft;
}

class ProposalSubmitting extends ProposalState {
  const ProposalSubmitting(this.draft);
  final ProposalDraft draft;
}

class ProposalDocumentsPending extends ProposalState {
  const ProposalDocumentsPending(this.draft, this.missingDocuments);
  final ProposalDraft draft;
  final List<String> missingDocuments;
}

class ProposalFailure extends ProposalState {
  const ProposalFailure(this.draft, this.message);
  final ProposalDraft draft;
  final String message;
}

Além do resultado, preserve no estado os dados necessários para recuperação: o rascunho preenchido, uma mensagem adequada ao usuário e, quando necessário, informações para tentar a ação novamente. Essa modelagem torna a programação reativa no Flutter mais próxima do fluxo real do negócio.

Organize providers por responsabilidade e ciclo de vida

Uma estrutura sustentável separa providers de infraestrutura, repositórios, casos de uso, parâmetros, dados derivados e estado de tela. Cada provider deve ter um nome que revele sua responsabilidade e um ciclo de vida escolhido conscientemente.

Use Provider para dependências estáveis, como cliente HTTP, repositório e caso de uso. Use Notifier quando o estado for síncrono e controlado por ações. Use AsyncNotifier quando o carregamento inicial depender de uma operação assíncrona. Para recursos identificados por parâmetro, use family.

final customerProvider = FutureProvider.family<Customer, String>((ref, customerId) {
  return ref.watch(customerRepositoryProvider).getById(customerId);
});

final proposalControllerProvider =
    NotifierProvider.autoDispose<ProposalController, ProposalState>(
  ProposalController.new,
);

O autoDispose é útil para estados ligados a uma tela ou fluxo temporário, mas não deve ser aplicado automaticamente a tudo. Dados que precisam sobreviver à navegação, como uma sessão ou configuração global, podem exigir outra estratégia. A injeção de dependências no Flutter fica mais explícita quando cada camada declara o que precisa por meio de ref.watch.

Em um fluxo de proposta, mantenha providers independentes para cliente, regras de elegibilidade, proposta atual e cálculo de parcelas. Um controller do fluxo pode compô-los sem transformar cada detalhe em estado global.

Implemente regras complexas sem acoplar a lógica ao provider

O notifier deve coordenar o fluxo, não decidir sozinho todas as regras do domínio. Quando uma regra é importante para a empresa — como limite diário, elegibilidade, disponibilidade ou permissão — ela precisa morar em um caso de uso, serviço de domínio ou política testável.

Considere a confirmação de uma proposta. O controller recebe a ação, impede duplicidade, muda o estado para envio e chama o caso de uso. O caso de uso consulta dados e aplica critérios; o controller interpreta o resultado e expõe a próxima fase para a interface.

class ProposalController extends Notifier<ProposalState> {
  @override
  ProposalState build() => ProposalEditing(ProposalDraft.empty());

  Future<void> submit() async {
    final current = state;
    if (current is! ProposalEditing) return;

    state = ProposalSubmitting(current.draft);
    final result = await ref.read(submitProposalUseCaseProvider)(current.draft);

    state = switch (result) {
      ProposalApproved() => ProposalApprovedState(result.proposal),
      ProposalNeedsDocuments() => ProposalDocumentsPending(current.draft, result.documents),
      ProposalRejected() => ProposalRejectedState(result.reason),
      ProposalError() => ProposalFailure(current.draft, result.message),
    };
  }
}

Essa composição mantém regras pequenas e substituíveis. Também reduz o risco de uma decisão ser implementada de forma diferente em duas telas. A validação de formulários Flutter pode cuidar da qualidade da entrada, enquanto o domínio confirma se aquela entrada é permitida no contexto real da operação.

Trate carregamento, erros, concorrência e estados assíncronos

Produção exige mais do que um indicador de carregamento. Diferencie o carregamento inicial de uma atualização em segundo plano, preserve dados úteis durante falhas temporárias e forneça caminhos de recuperação claros.

AsyncValue é útil para muitos cenários de busca de dados, pois representa carregamento, valor e erro. Em fluxos com muitas fases, um estado próprio costuma comunicar melhor o processo. A escolha deve privilegiar clareza, não uma regra rígida.

Também proteja ações contra concorrência. Se um usuário tocar duas vezes em “confirmar”, o segundo envio não deve gerar outra solicitação. Uma guarda baseada no estado atual resolve muitos casos; para operações que podem receber respostas fora de ordem, use um identificador de requisição ou confirme que a resposta ainda pertence ao estado ativo.

Ao atualizar um endereço, mantenha o endereço anterior visível enquanto a operação é enviada. Se houver falha, informe o problema de forma acionável e ofereça nova tentativa, em vez de limpar a tela. O tratamento de erros no Flutter deve ajudar tanto a experiência do usuário quanto o diagnóstico técnico por meio de monitoramento adequado.

Teste providers e regras de negócio com segurança

Uma das maiores vantagens dessa abordagem é testar comportamento sem depender da árvore de widgets. Teste primeiro os casos de uso, pois eles concentram a regra que não pode falhar. Depois, teste as transições do notifier com repositórios ou casos de uso substituídos.

test('não envia proposta quando a elegibilidade reprova', () async {
  final container = ProviderContainer(
    overrides: [
      submitProposalUseCaseProvider.overrideWithValue(FakeRejectedUseCase()),
    ],
  );
  addTearDown(container.dispose);

  final controller = container.read(proposalControllerProvider.notifier);
  await controller.submit();

  expect(container.read(proposalControllerProvider), isA<ProposalRejectedState>());
});

Use ProviderContainer para criar um ambiente isolado e overrides para trocar dependências reais por mocks ou fakes. Cubra sucesso, falha, bloqueio, pendência documental e repetição de ação. Nos testes unitários no Flutter, o objetivo não é apenas aumentar cobertura: é garantir que decisões críticas continuem corretas após uma mudança.

Fakes simples costumam ser mais legíveis do que mocks excessivamente configurados. Reserve mocks para verificar interações importantes, como assegurar que uma API não foi chamada quando uma regra de limite diário bloqueou a operação.

Checklist para levar Riverpod à produção

Antes de publicar um módulo, revise se a estrutura continua compreensível para alguém que não participou da implementação. Um bom módulo deve permitir localizar a regra, a dependência e o estado sem percorrer widgets extensos.

• Providers possuem responsabilidade única, nomes consistentes e ciclo de vida intencional.
• Widgets não executam regras de domínio nem acessam diretamente fontes de dados.
• Notifiers coordenam ações e transições, sem concentrar decisões reutilizáveis.
• Regras críticas têm testes automatizados de sucesso, falha e bloqueio.
• Erros preservam contexto útil e apresentam uma próxima ação para o usuário.
• Ações destrutivas ou remotas são protegidas contra disparos duplicados.
• Dependências externas podem ser substituídas em testes por overrides.
• Falhas relevantes são observáveis após a publicação.

Performance em apps Flutter também depende dessa disciplina. Providers pequenos e bem delimitados reduzem reconstruções desnecessárias e facilitam identificar o que realmente muda. Ainda assim, a prioridade deve ser medir antes de otimizar e preservar a legibilidade do fluxo.

Implementar Riverpod em Flutter com regras complexas não significa espalhar providers por todo o projeto. Significa definir limites claros: a interface comunica intenção, o notifier orquestra, o domínio decide e a infraestrutura entrega dados. Com essa base, o aplicativo cresce sem que cada nova regra torne o estado mais frágil.

Sua empresa precisa de um app Flutter robusto, com regras de negócio confiáveis e arquitetura preparada para evoluir? Conheça os serviços da Max Alex para desenvolvimento e modernização de aplicativos mobile.