Resiliência: estados de UI, retry e modo caos

No fim desta aula consegues

• Enumerar as formas como um pedido falha em mobile e o que a app deve fazer em cada uma.
• Explicar offline-first, cache HTTP com ETag e Cache-Control, paginação e rate limiting.
• Modelar o estado de um ecrã como sealed class e tratá-lo com um switch exaustivo.
• Implementar retry com backoff exponencial e jitter, e saber quando não repetir.
• Construir ecrãs de erro, vazio e loading que o utilizador percebe, com pull-to-refresh e idade dos dados.

Tudo falha

• Sem rede: modo avião, túnel, garagem. SocketException em milissegundos.
• Rede lenta: 3G fraco, Wi-Fi do café com portal de login. Um pedido de 20 segundos, ou um TimeoutException.
• Servidor em baixo: 500, 502, 503. Ou 429 porque a app pediu demais.
• JSON inesperado: campo a null, string onde devia estar um número, lista vazia. FormatException ou TypeError.
• Exemplos: o Spotify em modo offline continua a tocar o que descarregou; o Google Maps mostra o mapa em cache; a app do banco diz "sem ligação" mas mostra o último saldo.
• O pior resultado possível: ecrã em branco ou crash. O segundo pior: "Error: SocketException…".

Para os testes: em mobile a falha de rede não é uma exceção, é um caso normal; desenha-se a app para ela.

Offline-first

• Mostrar primeiro o que há. Se já houve dados alguma vez, nunca mostrar um ecrã vazio: mostra a cache, depois atualiza.
• Marcar como antigo. "Atualizado há 12 min", um ícone, uma cor. O utilizador decide se confia.
• Sincronizar quando der. Ao abrir a app, ao voltar a ter rede, ao puxar a lista. Não a cada segundo.
• Escritas offline: um favorito marcado sem rede vai para uma fila e sobe quando houver ligação. Conflitos resolvem-se com regras (o último ganha, ou o servidor ganha).
• Detetar ligação: connectivity_plus diz se há Wi-Fi ou dados, não se há Internet. A única prova é um pedido que responde.

Para os testes: offline-first é cache primeiro, rede depois, e dizer sempre ao utilizador a idade dos dados.

Cache HTTP: ETag, Cache-Control, 304

• ETag é uma impressão digital da resposta. O cliente guarda-a e envia If-None-Match: "abc" no pedido seguinte. Se nada mudou, o servidor responde 304 Not Modified sem corpo.
• Cache-Control: max-age=600 autoriza o cliente a reutilizar a resposta durante 10 minutos sem perguntar. no-store proíbe guardar (dados sensíveis).
• 304 poupa dados e bateria, mas ainda há um pedido. max-age evita o pedido de todo.
• Cache no cliente (a app guarda) e cache no servidor ou CDN (guardado para todos os utilizadores) coexistem.
• O package http não faz cache sozinho. Opções: dio + dio_cache_interceptor, ou a nossa base de dados local (aula 16).

Para os testes: ETag + If-None-Match dão 304 "não mudou"; Cache-Control diz durante quanto tempo a resposta é válida.

Paginação e rate limiting

• Rate limiting: o servidor limita pedidos por cliente (por exemplo 100 por minuto) e responde 429 Too Many Requests com Retry-After: 30.
• A app respeita o Retry-After. Repetir logo piora e pode levar a bloqueio do token.

Para os testes: 429 pede espera, não retry imediato; Retry-After diz quanto tempo.

Retry com backoff exponencial e jitter

• Backoff exponencial: espera 1 s, 2 s, 4 s, 8 s entre tentativas. Máximo de tentativas (3) e teto de espera (30 s).
• Jitter: uma parte aleatória em cada espera. Sem isto, mil telemóveis que falharam ao mesmo tempo repetem ao mesmo tempo e deitam o servidor abaixo outra vez (thundering herd).
• Repetir: timeouts, falhas de ligação, 5xx, 429 (respeitando Retry-After).
• Não repetir: 4xx (o pedido está errado, vai falhar outra vez) e POST não idempotente: criar dois favoritos, pagar duas vezes.
• Se um POST tem mesmo de ser repetido, usa uma chave de idempotência (Idempotency-Key), como o Stripe: o servidor ignora a repetição.

Para os testes: repetir só falhas transitórias, só pedidos idempotentes, com backoff exponencial e jitter.

Repositório da aula

git clone https://github.com/pdm-daw-2026/pdm-aula-14.git
cd pdm-aula-14/starter
flutter pub get
flutter run

• starter/ é a app de ontem (repository + notifier + Provider) com TODOs numerados de 1 a 5 e testes a falhar para cada estado.
• solucao/ é o estado final, e é o que vai aguentar o modo caos no fim da aula.
• Novo no pubspec.yaml: skeletonizer para o loading. Já está instalado.

1. O estado como sealed class

sealed class EstadoPrevisao {
  const EstadoPrevisao();
}

class Carregando extends EstadoPrevisao {
  const Carregando();
}

class Erro extends EstadoPrevisao {
  const Erro(this.mensagem, {this.podeRepetir = true});
  final String mensagem;
  final bool podeRepetir;
}

class Vazio extends EstadoPrevisao {
  const Vazio();
}

class Dados extends EstadoPrevisao {
  const Dados(this.localidades, {required this.obtidoEm});
  final List<Localidade> localidades;
  final DateTime obtidoEm;
}

1. O notifier passa a ter um só campo

class PrevisaoNotifier extends ChangeNotifier {
  PrevisaoNotifier(this._repo);
  final PrevisaoRepository _repo;

  EstadoPrevisao estado = const Carregando();

  Future<void> carregar({bool silencioso = false}) async {
    if (!silencioso) {
      estado = const Carregando();
      notifyListeners();
    }
    try {
      final lista = await _repo.localidades();
      estado = lista.isEmpty
          ? const Vazio()
          : Dados(lista, obtidoEm: DateTime.now());
    } on ApiException catch (e) {
      estado = Erro(mensagemPara(e), podeRepetir: e.transitoria);
    } catch (e) {
      estado = Erro(mensagemPara(e));
    }
    notifyListeners();
  }
}

1. switch exaustivo na UI

@override
Widget build(BuildContext context) {
  final estado = context.watch<PrevisaoNotifier>().estado;

  return switch (estado) {
    Carregando() => const ListaSkeleton(),
    Vazio() => EstadoVazio(
        mensagem: 'Ainda não há localidades.',
        acao: 'Atualizar',
        aoAgir: () => context.read<PrevisaoNotifier>().carregar(),
      ),
    Erro(:final mensagem, :final podeRepetir) => EstadoErro(
        mensagem: mensagem,
        aoRepetir: podeRepetir
            ? () => context.read<PrevisaoNotifier>().carregar()
            : null,
      ),
    Dados(:final localidades, :final obtidoEm) => ListaLocalidades(
        localidades: localidades,
        obtidoEm: obtidoEm,
      ),
  };
}

1. Estados: o que interessa

• sealed fecha a hierarquia: só estas quatro subclasses existem. O compilador sabe-o e obriga o switch a tratar todas.
• Acrescenta um estado Parcial e o build deixa de compilar até o tratares. É impossível esquecer um caso.
• Com três booleanos (aCarregar, erro, lista) havia oito combinações, quatro delas impossíveis. Agora há quatro estados, todos possíveis.
• Erro(:final mensagem) é um object pattern: extrai o campo no próprio case.
• Os dados vivem dentro do estado (Dados.localidades): não há lista "pendurada" quando o estado é Erro.

2. Widgets de erro, vazio e loading

class EstadoErro extends StatelessWidget {
  const EstadoErro({super.key, required this.mensagem, this.aoRepetir});
  final String mensagem;
  final VoidCallback? aoRepetir;

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          const Icon(Icons.cloud_off, size: 48),
          const SizedBox(height: 12),
          Text(mensagem, textAlign: TextAlign.center),
          if (aoRepetir != null) ...[
            const SizedBox(height: 12),
            FilledButton.icon(
              onPressed: aoRepetir,
              icon: const Icon(Icons.refresh),
              label: const Text('Tentar de novo'),
            ),
          ],
        ],
      ),
    );
  }
}

2. Estados visuais: o que interessa

• Erro: ícone, mensagem humana e um botão "Tentar de novo" só quando faz sentido (aoRepetir nulo esconde-o). Um 404 não se repete.
• Vazio: não é erro. "Ainda não há avisos" com um ícone calmo e, se possível, uma ação ("Atualizar", "Adicionar favorito").
• Loading: um skeleton em vez de um spinner ao centro: Skeletonizer(enabled: true, child: ListaLocalidades(localidades: Localidade.exemplo)) desenha a forma da lista a cinzento.
• Os três são widgets reutilizáveis em lib/core/widgets/: cada ecrã do projeto usa os mesmos.
• Os estados fazem parte do design (aula 6): desenham-se com o mesmo cuidado que o ecrã com dados.

3. Retry com backoff no ApiClient

Future<dynamic> get(String caminho, {int tentativas = 3}) async {
  var espera = const Duration(seconds: 1);
  for (var i = 1; ; i++) {
    try {
      return await _getUmaVez(caminho);          // o get da aula 12
    } on ApiException catch (e) {
      if (!e.transitoria || i >= tentativas) rethrow;
      await Future.delayed(e.retryAfter ?? _comJitter(espera));
    } on TimeoutException catch (_) {
      if (i >= tentativas) rethrow;
      await Future.delayed(_comJitter(espera));
    } on SocketException catch (_) {
      if (i >= tentativas) rethrow;
      await Future.delayed(_comJitter(espera));
    }
    espera *= 2;                                   // 1 s, 2 s, 4 s
  }
}

Duration _comJitter(Duration base) =>
    base + Duration(milliseconds: Random().nextInt(300));

// Em ApiException: 429 e 5xx são transitórios; 4xx não
bool get transitoria => statusCode == 429 || (statusCode ?? 0) >= 500;

3. Mensagens humanas por tipo de falha

String mensagemPara(Object erro) => switch (erro) {
      SocketException() => 'Sem ligação. Verifica a rede e tenta de novo.',
      TimeoutException() => 'O servidor está a demorar. Tenta daqui a pouco.',
      ApiException(statusCode: 429) => 'Muitos pedidos seguidos. Espera uns segundos.',
      ApiException(statusCode: 401) => 'A sessão expirou. Volta a entrar.',
      ApiException(statusCode: final c?) when c >= 500 =>
        'O serviço está com problemas. Mostramos os últimos dados que temos.',
      FormatException() => 'Recebemos dados inesperados. Já estamos a tratar disso.',
      _ => 'Algo correu mal. Tenta de novo.',
    };

• Só o get repete: post e delete falham à primeira, porque não são idempotentes.
• retryAfter vem do header Retry-After em segundos; o starter já o lê em _getUmaVez.
• Uma mensagem por tipo de falha, sem jargão, e a dizer o que o utilizador pode fazer. A exceção original vai para o log.

4. Pull-to-refresh e idade dos dados

class ListaLocalidades extends StatelessWidget {
  const ListaLocalidades({super.key, required this.localidades, required this.obtidoEm});
  final List<Localidade> localidades;
  final DateTime obtidoEm;

  @override
  Widget build(BuildContext context) {
    final minutos = DateTime.now().difference(obtidoEm).inMinutes;
    return RefreshIndicator(
      onRefresh: () => context.read<PrevisaoNotifier>().carregar(silencioso: true),
      child: ListView.builder(
        physics: const AlwaysScrollableScrollPhysics(),
        itemCount: localidades.length + 1,
        itemBuilder: (_, i) {
          if (i == 0) {
            return ListTile(
              dense: true,
              leading: const Icon(Icons.schedule, size: 18),
              title: Text(minutos == 0 ? 'Atualizado agora' : 'Dados de há $minutos min'),
            );
          }
          return ListTile(title: Text(localidades[i - 1].nome), subtitle: Text(localidades[i - 1].ilha));
        },
      ),
    );
  }
}

4. Refresh: o que interessa

• RefreshIndicator chama onRefresh e mantém o círculo visível até o Future terminar. Por isso carregar devolve Future<void>.
• silencioso: true não passa por Carregando: a lista fica visível durante o refresh. Sem isto, o skeleton substituía a lista e o gesto parecia partido.
• AlwaysScrollableScrollPhysics permite puxar mesmo quando a lista cabe no ecrã.
• "Dados de há 12 min" só faz sentido se obtidoEm viver no estado. É por isso que está em Dados, não no widget.
• Um refresh que falha com dados no ecrã mostra um SnackBar e mantém os dados: nunca troca dados válidos por um ecrã de erro.

5. Modo caos: observar, corrigir, repetir

1. O docente liga o modo caos ao teu grupo: latência de 3 s em metade dos pedidos, 20% de respostas 500, um 429 a cada dez pedidos com Retry-After: 5.
2. Usa a app durante dois minutos como um utilizador: abre a lista, entra num detalhe, puxa para atualizar, volta. Anota tudo o que vês e não devias ver.
3. Corrige por ordem de gravidade: crash ou ecrã em branco, depois mensagens cruas, depois retry a bater no 429, depois dados válidos substituídos por erro.
4. Repete até a app aguentar cinco minutos de caos sem crash, sem ecrã em branco e sem mensagem técnica.

Até amanhã