Arquitetura por camadas e gestão de estado

No fim desta aula consegues

• Explicar porque se separa uma app em camadas e o que cada camada pode conhecer.
• Escrever um repository com uma interface e uma implementação HTTP.
• Guardar o estado de um ecrã (a carregar, erro, dados) num ChangeNotifier.
• Ligar o notifier ao ecrã com o Provider: context.watch, context.read e Consumer.
• Injetar dependências pelo construtor e trocar a API por um repository a fingir sem mexer no ecrã.
• Partilhar estado entre dois ecrãs.

O ecrã que faz tudo

class _IslandsScreenState extends State<IslandsScreen> {
  late Future<List<Island>> _islands;

  @override
  void initState() {
    super.initState();
    _islands = _load();
  }

  Future<List<Island>> _load() async {
    final list = await widget.api.get('/v1/islands') as List<dynamic>;
    return list
        .map((item) => Island.fromJson(item as Map<String, dynamic>))
        .toList();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Tempo Açores')),
      body: FutureBuilder<List<Island>>(
        future: _islands,
        builder: (context, snapshot) {
          // a carregar, erro e dados, como na última aula

• É o FutureBuilder da última aula, e funciona. Mas este ecrã sabe o caminho da API, sabe ler o JSON, guarda o Future e decide o que mostrar em cada estado.
• O ApiClient trata do token, dos headers, dos códigos de estado e do jsonDecode. Não sabe o que é uma ilha.

Porquê camadas

• Trocar a fonte dos dados. A API muda de versão, os dados passam a vir também de uma cache no telemóvel: muda um ficheiro, e os ecrãs ficam iguais.
• Mostrar sem rede. Um repository a fingir, com dados fixos, deixa desenvolver e demonstrar o ecrã sem API e sem credenciais. Mais à frente, é também o que torna os testes automáticos possíveis.
• Reutilizar. A lista de ilhas aparece na lista, nos favoritos e, um dia, no mapa: um só sítio sabe ir buscá-la.
• Cada pessoa no seu ficheiro. No projeto de grupo, quem faz o ecrã e quem faz os pedidos não mexem no mesmo ficheiro ao mesmo tempo.

Numa app grande (a do banco, a do Spotify) o ecrã pede "a conta" e não sabe se ela veio da rede, da cache ou do disco.

Para os testes: as camadas existem para isolar mudanças; o ecrã não deve conhecer HTTP nem JSON.

UI, notifier, repository e data source

Para os testes: as dependências apontam só para baixo; o repository é a fronteira entre a app e os dados.

Repository: uma interface, várias implementações

/// What the app can ask for. The screens only see this.
abstract class ForecastRepository {
  Future<List<Island>> fetchIslands();
  Future<Forecast> fetchForecast(String islandId);
}

• A interface diz o quê: as ilhas, a previsão de uma ilha. Uma abstract class sem corpo nos métodos.
• Cada implementação diz como: HttpForecastRepository pede à API; FakeForecastRepository devolve dados fixos; mais à frente, uma com cache no telemóvel.
• Quem usa recebe um ForecastRepository e não sabe qual dos três é.
• O JSON não passa daqui para cima. O fromJson converte a forma da API (o DTO) na forma da app (o modelo); se a API mudar um nome, muda o fromJson, e o resto da app fica igual.

Para os testes: repository = uma interface com várias implementações; o ecrã depende da interface, nunca da implementação.

Injeção de dependências: quem usa não cria

final ForecastRepository repository = useFake
    ? FakeForecastRepository()
    : HttpForecastRepository(
        ApiClient(clientId: clientId, clientSecret: clientSecret),
      );

• O HttpForecastRepository recebe o ApiClient no construtor; o ForecastNotifier recebe o repository no construtor. Nenhum deles cria aquilo de que precisa.
• Quem cria é o main, num só sítio. É aí que se escolhe a API ou o fake, e as credenciais.
• O contrário, um ApiClient() criado dentro do notifier ou uma variável global que todos usam, é uma dependência escondida: não se troca, e não se vê quem depende de quem.
• Para levar os objetos até aos widgets usamos o Provider. Há outras ferramentas (get_it, Riverpod); a regra do construtor é a mesma.

Para os testes: injeção de dependências = receber pelo construtor em vez de criar; permite trocar uma peça sem mexer em quem a usa.

Quando chega o Provider

• O Provider chega quando o estado sai de um só widget: quando dois ecrãs precisam dele, quando tem de sobreviver à navegação, ou quando a lógica deve viver fora dos widgets.
• A recomendação da equipa do Flutter: começar simples, com camadas e injeção pelo construtor, e só depois trocar de ferramenta se for preciso. Com as camadas feitas, trocar o ChangeNotifier por BLoC é mexer numa camada; sem elas, é reescrever ecrãs.

Para os testes: a arquitetura certa é a mais simples que resolve o problema de hoje, com fronteiras que a deixam crescer.

ChangeNotifier e Provider: as peças

• Regra para dizer em voz alta: watch no build, read nos callbacks.
• O Provider é um InheritedWidget com menos cerimónia, o mesmo mecanismo do Theme.of(context): um valor posto em cima na árvore, que qualquer widget de baixo encontra pelo context.

Para os testes: notifyListeners avisa; watch reconstrói; read não; o Provider tem de estar acima de quem o lê.

Começar: o repositório de hoje

git clone https://github.com/Tiago-Rocha/pdm-aula-13.git
cd pdm-aula-13
flutter pub get

1. Abre a pasta no VS Code. O clientId e o clientSecret estão na issue #1 do teu repositório pdm-miniprojeto.
2. No terminal do VS Code, numa só linha, com os teus valores: flutter run -d chrome --dart-define=CLIENT_ID=pdm-ab12cd --dart-define=CLIENT_SECRET=o-teu-segredo
3. Tens de ver a lista das ilhas, cada uma com a fotografia. Mão no ar quando aparecer.
4. Abre um segundo terminal (o + do painel do terminal) para os comandos git. No primeiro, onde corre a app, r é hot reload, R é hot restart e q fecha.

1. O repository: o pedido sai do ecrã

/// How: HTTP to the course API, through the ApiClient.
class HttpForecastRepository implements ForecastRepository {
  HttpForecastRepository(this._api); // injected, not created here

  final ApiClient _api;

  @override
  Future<List<Island>> fetchIslands() async {
    final list = await _api.get('/v1/islands') as List<dynamic>;
    return list
        .map((item) => Island.fromJson(item as Map<String, dynamic>))
        .toList();
  }

  @override
  Future<Forecast> fetchForecast(String islandId) async {
    final json = await _api.get('/v1/islands/$islandId/forecast');
    return Forecast.fromJson(json as Map<String, dynamic>);
  }
}

• O fetchIslands é o _load do ecrã, mudado de sítio: o caminho e o fromJson vivem agora aqui.
• implements ForecastRepository obriga a escrever os dois métodos da interface, com @override. Se faltar um, o código não compila.
• O fetchForecast fica pronto para mais à frente: hoje ninguém o chama.

Passo 1: o ecrã recebe o repository

import 'forecast_repository.dart';
import 'models.dart';

  const IslandsScreen({super.key, required this.repository});

  final ForecastRepository repository;

// no initState, e no botão Tentar de novo dentro do setState:
    _islands = widget.repository.fetchIslands();

  final api = ApiClient(clientId: clientId, clientSecret: clientSecret);
  final repository = HttpForecastRepository(api);

      home: IslandsScreen(repository: repository),

Na app: a mesma lista de ilhas, e é esse o objetivo. O ecrã já não sabe caminhos nem JSON.

2. ForecastNotifier: o estado sai do ecrã

/// The state of the islands screen. Knows the repository, not the widgets.
class ForecastNotifier extends ChangeNotifier {
  ForecastNotifier(this._repository); // injected, not created here

  final ForecastRepository _repository;

  bool isLoading = false;
  String? error;
  List<Island> islands = const [];

  Future<void> load() async {
    isLoading = true;
    error = null;
    notifyListeners(); // the screen shows the spinner
    try {
      islands = await _repository.fetchIslands();
    } catch (e) {
      error = '$e';
    } finally {
      isLoading = false;
      notifyListeners(); // the screen shows the islands or the error
    }
  }
}

• Os três estados do FutureBuilder passam a ser três campos: isLoading, error e islands.
• O notifier não conhece widgets nem BuildContext. Importa foundation.dart, não material.dart.

2. O Provider fica por cima do MaterialApp

void main() {
  final api = ApiClient(clientId: clientId, clientSecret: clientSecret);
  final repository = HttpForecastRepository(api);
  runApp(
    ChangeNotifierProvider(
      create: (_) => ForecastNotifier(repository)..load(),
      child: MaterialApp(
        title: 'Tempo Açores',
        theme: ThemeData(colorSchemeSeed: Colors.teal),
        home: const IslandsScreen(),
      ),
    ),
  );
}

• O create corre uma vez: cria o notifier com o repository e o ..load() lança logo o primeiro pedido. Os .. chamam load() e devolvem o notifier.
• O IslandsScreen deixou de receber parâmetros: vai buscar o notifier ao Provider.
• Tudo o que está abaixo do ChangeNotifierProvider o encontra. Por cima do MaterialApp, isso quer dizer todos os ecrãs da app.

Passo 2: o ecrã só conhece o notifier

git stash -u
git checkout passo-1
flutter pub get

class IslandsScreen extends StatelessWidget {
  const IslandsScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final forecast = context.watch<ForecastNotifier>(); // rebuilds on notify
    return Scaffold(
      appBar: AppBar(title: const Text('Tempo Açores')),
      body: _body(context, forecast),
    );
  }

  Widget _body(BuildContext context, ForecastNotifier forecast) {
    if (forecast.isLoading) {
      return const Center(child: CircularProgressIndicator());
    }
    // o erro: o Center de antes, com Text(forecast.error!) e
    onPressed: () => context.read<ForecastNotifier>().load(),
    // os dados: o ListView.builder de antes, com forecast.islands
  }
}

Na app: a mesma lista, outra vez. A diferença está no código: o ecrã ficou sem State, sem Future e sem FutureBuilder, e o estado vive no notifier.

3. Um repository a fingir

/// Same interface, fixed data: no API and no credentials.
class FakeForecastRepository implements ForecastRepository {
  FakeForecastRepository({this.fail = false});

  final bool fail; // true: shows the error screen

  @override
  Future<List<Island>> fetchIslands() async {
    await Future.delayed(const Duration(seconds: 1)); // a slow network
    if (fail) throw Exception('Sem rede (fake)');
    return const [
      Island(id: 'corvo', name: 'Corvo', imageUrl: '$_img/corvo.jpg'),
      Island(id: 'faial', name: 'Faial', imageUrl: '$_img/faial.jpg'),
      Island(id: 'pico', name: 'Pico', imageUrl: '$_img/pico.jpg'),
    ];
  }

  @override
  Future<Forecast> fetchForecast(String islandId) {
    throw UnimplementedError(); // not used yet
  }
}

const _img = 'https://api-pdm.sublimecipher.com/static/islands';

• Implementa a mesma interface. O notifier recebe um ForecastRepository e não sabe que este é a fingir.
• O segundo de espera deixa ver o "a carregar"; o fail: true deixa ver o ecrã de erro sem desligar o Wi-Fi.
• Serve para desenvolver o ecrã antes de a API existir, para demonstrar a app sem rede e, mais à frente, para testes automáticos.

Passo 3: trocar a API pelo fake

git stash -u
git checkout passo-2
flutter pub get

const useFake = bool.fromEnvironment('FAKE'); // --dart-define=FAKE=true

  final ForecastRepository repository = useFake
      ? FakeForecastRepository()
      : HttpForecastRepository(
          ApiClient(clientId: clientId, clientSecret: clientSecret),
        );

Na app: um segundo a carregar e depois três ilhas, sem credenciais. Muda para FakeForecastRepository(fail: true), R: aparece Exception: Sem rede (fake), e "Tentar de novo" mostra o "a carregar" antes de voltar ao erro.

4. Favoritas: estado partilhado por dois ecrãs

/// Favourite islands, in memory. Shared by two screens.
class FavoritesNotifier extends ChangeNotifier {
  final Set<String> _ids = {};

  int get count => _ids.length;
  bool contains(String islandId) => _ids.contains(islandId);

  void toggle(String islandId) {
    if (!_ids.remove(islandId)) _ids.add(islandId);
    notifyListeners();
  }
}

    MultiProvider(
      providers: [
        ChangeNotifierProvider(
          create: (_) => ForecastNotifier(repository)..load(),
        ),
        ChangeNotifierProvider(create: (_) => FavoritesNotifier()),
      ],

• Guarda só os id das ilhas, num Set: uma ilha é favorita ou não, sem repetições. O Set é privado; quem está fora só pode perguntar (contains, count) e pedir (toggle).
• O MultiProvider é uma lista de providers em vez de vários encaixados uns nos outros. O child continua a ser o MaterialApp.

4. A estrela e o contador

/// The star of one island. Used by both screens.
class FavoriteButton extends StatelessWidget {
  const FavoriteButton({super.key, required this.islandId});

  final String islandId;

  @override
  Widget build(BuildContext context) {
    final favorite = context.watch<FavoritesNotifier>().contains(islandId);
    return IconButton(
      icon: Icon(favorite ? Icons.star : Icons.star_border),
      onPressed: () => context.read<FavoritesNotifier>().toggle(islandId),
    );
  }
}

Consumer<FavoritesNotifier>(
  builder: (context, favorites, child) => IconButton(
    icon: Badge(
      isLabelVisible: favorites.count > 0,
      label: Text('${favorites.count}'),
      child: const Icon(Icons.star),
    ),
    onPressed: () => Navigator.push(
      context,
      MaterialPageRoute(builder: (_) => const FavoritesScreen()),
    ),
  ),
),

Passo 4: o ecrã das favoritas

git stash -u
git checkout passo-3
flutter pub get

class FavoritesScreen extends StatelessWidget {
  const FavoritesScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final favorites = context.watch<FavoritesNotifier>();
    final islands = context
        .watch<ForecastNotifier>()
        .islands
        .where((island) => '...')
        .toList();
    return Scaffold(
      appBar: AppBar(title: const Text('Favoritas')),
      // body: sem favoritas, 'Ainda não há ilhas favoritas.' ao centro;
      // com favoritas, uma ListView com um ListTile por ilha:
      // o nome no title e trailing: FavoriteButton(islandId: island.id)
    );
  }
}

Na app: marcas o Pico e o Corvo e o contador mostra 2. A estrela de cima abre as Favoritas com os dois; tiras o Corvo lá, voltas atrás: na lista o Corvo já não tem estrela e o contador mostra 1.

Onde ficámos

1. ForecastRepository com a interface e o HttpForecastRepository, que recebe o ApiClient: o pedido e o JSON saem do ecrã (passo 1).
2. ForecastNotifier com isLoading, error e islands, num ChangeNotifierProvider por cima do MaterialApp; o ecrã é um StatelessWidget com watch e read (passo 2).
3. FakeForecastRepository: a mesma interface, sem API; o main escolhe qual usar e mais nada muda (passo 3).
4. FavoritesNotifier partilhado pela lista e pelas Favoritas, com MultiProvider, Consumer e um FavoriteButton (passo 4).

O branch passo-4 é o estado final: compara o teu código com ele.

Até amanhã