Skip to content

9. Comunicando-se com o servidor

O servidor JSON [RdvMedecins] agora deve estar em execução (porta 8080), como explicado no capítulo anterior.

9.1. Exemplo 22: uma primeira requisição HTTP

9.1.1. Onde está o servidor?

Para um cliente web servido pelo próprio servidor, a pergunta não se coloca: as requisições são enviadas à mesma origem da página, usando um endereço relativo ([/api/captcha]). Uma aplicação mobile não tem origem: é preciso informar a ela o endereço completo do servidor. E esse endereço depende de onde a aplicação está sendo executada:

// =========================================================================
// lib/common/config.dart - ONDE está o servidor JSON?
// -------------------------------------------------------------------------
// A pergunta não se coloca para um aplicativo web servido pelo próprio
// servidor: as requisições vão para a MESMA origem da página
// (um endereço relativo, /api/...). Mas um aplicativo MOBILE não tem
// origem: é preciso informar a ele o endereço completo do servidor.
//   - o emulador Android enxerga o computador que o executa no
//     endereço 10.0.2.2 (localhost, para ele, é o próprio emulador);
//   - um celular de verdade, conectado à mesma rede Wi-Fi do computador, deve
//     usar o endereço do computador nessa rede (192.168.1.20...):
//     ele é informado quando o aplicativo é iniciado:
//         flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...
//   - no desenvolvimento web (flutter run -d chrome), o servidor de
//     desenvolvimento do Flutter encaminha as requisições /api para o servidor JSON
//     (arquivo web_dev_config.yaml): um endereço relativo basta;
//   - em um computador (Windows, macOS, Linux): localhost.
// =========================================================================

import 'package:flutter/foundation.dart';

// o valor dado por --dart-define=SERVER=..., '' por padrão.
// String.fromEnvironment é avaliado em tempo de COMPILAÇÃO: é uma constante
const _forcedServer = String.fromEnvironment('SERVER');

class Config {
  // kIsWeb: true se o aplicativo roda em um navegador;
  // defaultTargetPlatform: o sistema (android, iOS, windows...)
  static String serverUrl = _forcedServer.isNotEmpty
      ? _forcedServer
      : kIsWeb
      ? '' // mesma origem: endereços relativos
      : defaultTargetPlatform == TargetPlatform.android
      ? 'http://10.0.2.2:8080'
      : 'http://localhost:8080';
}
  • linha 24: um endereço informado na inicialização da aplicação, por meio da opção [--dart-define]: [flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...]. [String.fromEnvironment] é avaliado em tempo de compilação: é uma constante, “”, se a opção não for informada;
  • Linhas 29–35: caso contrário, um endereço padrão, dependendo da plataforma. [kIsWeb] é verdadeiro se a aplicação estiver sendo executada em um navegador; [defaultTargetPlatform] indica em qual sistema ela está sendo executada ([TargetPlatform.android], [TargetPlatform.windows]...):
    • na web: um endereço relativo (''), a mesma origem da aplicação;
    • no emulador [Android]: [http://10.0.2.2:8080]. O emulador é uma máquina independente, com sua própria rede: para o emulador, [localhost] refere-se ao próprio emulador. O endereço especial [10.0.2.2] refere-se ao computador que o executa;
    • em um computador ([Windows]...): [http://localhost:8080].

Um celular real, conectado à mesma rede Wi-Fi do computador do servidor, deve usar o endereço do computador nessa rede (o comando [ipconfig] do [Windows] o fornece): ele é informado por meio de [--dart-define]. O firewall do computador também deve permitir conexões de entrada na porta 8080.

Duas configurações no projeto [Android] são necessárias, no arquivo [android/app/src/main/AndroidManifest.xml]:

1
2
3
4
5
6
7
8
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- acesso à rede (o servidor JSON) -->
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:label="examples_flutter"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        android:usesCleartextTraffic="true">
  • linha 3: permissão para usar a rede. Durante o desenvolvimento, o [Flutter] a adiciona automaticamente (para o hot reload); ela deve ser declarada explicitamente na aplicação publicada;
  • Linha 8: a partir da versão 9 do [Android], uma aplicação só pode se comunicar via HTTPS. Nosso servidor de desenvolvimento usa HTTP (“sem criptografia”): nós o permitimos. Em produção, o servidor usaria HTTPS, e esta linha seria removida.

E para a web: o servidor de desenvolvimento do [Flutter] ([flutter run -d chrome]) serve a aplicação em sua própria porta; o servidor JSON, por sua vez, está na porta 8080. São duas origens diferentes: o navegador se recusaria a incluir o cookie nas requisições e até a lê-lo nas respostas (o servidor não permite requisições de uma origem diferente, ou seja, o “CORS”). O arquivo [web_dev_config.yaml] configura o servidor de desenvolvimento web do [Flutter] (desde a versão 3.38):

# ==========================================================================
# web_dev_config.yaml - o servidor de desenvolvimento WEB do Flutter
# --------------------------------------------------------------------------
# flutter run -d chrome serve o aplicativo em http://localhost:5173 e
# encaminha toda requisição /api/... ao servidor JSON do RdvMedecins (porta 8080):
# para o navegador, o aplicativo e a API têm a MESMA origem (sem
# CORS, e o cookie do token trafega). Exemplos 22 a 25.
# ==========================================================================

server:
  host: localhost
  port: 5173
  proxy:
    - target: "http://localhost:8080/"
      prefix: "/api/"
  • linha 12: a aplicação web é servida na porta 5173;
  • linhas 13–15: um proxy: qualquer requisição a um endereço que comece com [/api/] é encaminhada ao servidor JSON (porta 8080), e sua resposta é devolvida ao navegador. Para o navegador, a aplicação e a API têm a mesma origem. É exatamente o papel do proxy do [Vite] no curso de [React].

9.1.2. A requisição

// =========================================================================
// lib/ex22_http/main.dart - uma primeira requisição HTTP ao servidor
// -------------------------------------------------------------------------
// O servidor JSON do RdvMedecins deve estar iniciado (porta 8080). Pedimos a ele
// um captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - http.get(uri): a função do pacote http que envia uma
//     requisição GET. Ela retorna um Future da resposta (http.Response): seu código
//     de status (statusCode), seus cabeçalhos (headers), seu corpo (body);
//   - jsonDecode(text): o corpo JSON -> objetos Dart (Map, List...);
//   - o endereço do servidor depende de onde o aplicativo roda
//     (emulador Android, celular, navegador...): veja common/config.dart;
//   - três estados a exibir: em andamento, bem-sucedido, com falha;
//   - a imagem do captcha é SVG: o pacote flutter_svg sabe desenhá-la.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';
import 'package:http/http.dart' as http;

import '../common/config.dart';

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const CaptchaPage(),
    ),
  );
}

class CaptchaPage extends StatefulWidget {
  const CaptchaPage({super.key});

  @override
  State<CaptchaPage> createState() => _CaptchaPageState();
}

class _CaptchaPageState extends State<CaptchaPage> {
  // o que GET /api/captcha retorna: um record
  ({String id, String svg})? _captcha;
  bool _loading = true;
  String? _error;
  int _requestCount = 0;
  int _requestNumber = 0; // o número da última requisição

  @override
  void initState() {
    super.initState();
    _load(); // a primeira requisição, assim que a tela aparece
  }

  Future<void> _load() async {
    final number = ++_requestNumber;
    setState(() {
      _loading = true;
      _error = null;
    });
    try {
      final response = await http.get(Uri.parse('${Config.serverUrl}/api/captcha'));
      // http.get NÃO lança exceção para uma resposta de erro (4xx,
      // 5xx): o código de status é testado
      if (response.statusCode != 200) {
        throw Exception('the server answered ${response.statusCode} ${response.reasonPhrase}');
      }
      final json = jsonDecode(response.body) as Map<String, dynamic>;
      // a resposta de uma requisição OBSOLETA (uma nova foi feita nesse meio-tempo), ou
      // uma que chegou depois que a tela foi fechada: ela é ignorada
      if (!mounted || number != _requestNumber) return;
      setState(() {
        _captcha = (id: json['id'] as String, svg: json['svg'] as String);
        _requestCount++;
        _loading = false;
      });
    } catch (e) {
      // nenhuma resposta (servidor parado, endereço errado...), ou um erro
      if (!mounted || number != _requestNumber) return;
      setState(() {
        _error = '$e';
        _captcha = null;
        _loading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    final captcha = _captcha;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 22 - a first HTTP request')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Text(
            'Server: ${Config.serverUrl.isEmpty ? '(same origin)' : Config.serverUrl}',
            style: const TextStyle(color: Colors.grey),
          ),
          const SizedBox(height: 12),
          if (_loading) const LinearProgressIndicator(),
          if (_error != null)
            Card(
              color: Colors.red.shade50,
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: Text(
                  'Unable to get a captcha: $_error.\n'
                  'Is the RdvMedecins JSON server started (port 8080)?',
                ),
              ),
            ),
          if (captcha != null && !_loading) ...[
            // SvgPicture.string: desenhar uma imagem SVG dada como texto
            Container(
              padding: const EdgeInsets.all(4),
              decoration: BoxDecoration(
                border: Border.all(color: Colors.grey.shade300),
                borderRadius: BorderRadius.circular(6),
              ),
              child: SvgPicture.string(captcha.svg, height: 60),
            ),
            const SizedBox(height: 8),
            Text('id: ${captcha.id}', style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 11)),
          ],
          const SizedBox(height: 12),
          Align(
            alignment: Alignment.centerLeft,
            child: FilledButton(onPressed: _loading ? null : _load, child: const Text('Another image')),
          ),
          const SizedBox(height: 8),
          Text('$_requestCount successful request(s)', style: const TextStyle(color: Colors.grey)),
        ],
      ),
    );
  }
}
  • linha 21: o pacote [http], o cliente HTTP da equipe do [Dart]. [as http]: suas funções são usadas com um prefixo ([http.get], [http.Response]), o que evita que seus nomes sejam confundidos com outros;
  • linhas 44–48: o estado: o CAPTCHA recebido (um record, ou [null]), os três estados de uma requisição (em andamento, erro, bem-sucedida), o número de requisições bem-sucedidas;
  • linhas 51–53: a primeira requisição é enviada assim que a tela aparece;
  • linhas 56–84: a requisição:
    • linha 63: [http.get] envia uma requisição GET e devolve mais tarde um [Future<http.Response>]: a resposta. [Uri.parse] constrói o endereço a partir de uma string;
    • linhas 66–67: [http.get] NÃO lança uma exceção para uma resposta de erro (4xx, 5xx): é apenas mais uma resposta. Verificamos seu código de status;
    • linha 69: [response.body] é o corpo da resposta, o texto; [jsonDecode] o converte em objetos [Dart]: neste caso, um [Map];
    • linha 72: a resposta a uma requisição DESATUALIZADA (uma imagem foi solicitada novamente nesse meio-tempo), ou que chega depois que a tela foi fechada, é ignorada (veja o exemplo 19);
    • linha 74: o JSON é do tipo [dynamic]: cada valor é convertido para o tipo correspondente, graças ao [as];
    • linhas 78–82: nenhuma resposta (servidor fora do ar, endereço incorreto, rede desconectada): [http.get] lança uma exceção, que é capturada e exibida;
  • linha 102: uma barra de progresso durante a requisição;
  • linha 122: a imagem do CAPTCHA é um SVG, em forma de texto: [SvgPicture.string] (pacote [flutter_svg]) a renderiza. Ela é gerada pelo NOSSO servidor e não contém nada fornecido por um usuário;
  • linha 130: “Outra imagem”, desabilitado durante uma requisição.

No emulador [Android]; depois, com o servidor JSON desligado:

A ferramenta [Flutter DevTools] (iniciada pelo [VS Code], ou pelo endereço fornecido por [flutter run]) tem uma aba Network que exibe cada requisição HTTP da aplicação, com seus cabeçalhos e corpo, de forma semelhante às ferramentas de desenvolvedor de um navegador.

9.2.1. Um cliente HTTP que gerencia cookies

O servidor armazena o token JWT em um cookie. Em um navegador, é o navegador que cuida de armazenar e enviar os cookies; o código da aplicação não precisa fazer nada. Em um celular, NÃO há navegador: cabe à aplicação cuidar disso.

// =========================================================================
// lib/common/http_client.dart - um cliente HTTP que gerencia COOKIES
// -------------------------------------------------------------------------
// O servidor RdvMedecins coloca o token JWT em um COOKIE (httpOnly).
// Em um navegador, é o navegador que guarda os cookies e os envia
// de volta a cada requisição: o código do aplicativo não tem nada a fazer.
// Em um celular, NÃO há navegador: cabe ao aplicativo
// desempenhar seu papel, ou seja:
//   1. ler o cabeçalho "Set-Cookie" de cada resposta e guardar os cookies;
//   2. enviá-los de volta no cabeçalho "Cookie" de cada requisição.
// Este cliente HTTP faz isso, ENVOLVENDO o cliente do pacote http
// (http.BaseClient: basta escrever o método send). Os cookies são
// também guardados no dispositivo (shared_preferences): continuamos logados
// quando paramos e reiniciamos o aplicativo.
// Na web, ele não faz nada além do cliente comum: o
// navegador proíbe o aplicativo de ler ou escrever esses cabeçalhos.
// =========================================================================

import 'dart:convert';

import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';

class CookieClient extends http.BaseClient {
  static const _key = 'rdvmedecins.cookies';

  final http.Client _inner = http.Client();
  final SharedPreferences? _storage;
  // nome do cookie -> seu valor
  final Map<String, String> _cookies = {};

  CookieClient([this._storage]) {
    // os cookies guardados durante um uso anterior
    final stored = _storage?.getString(_key);
    if (stored != null) {
      _cookies.addAll((jsonDecode(stored) as Map<String, Object?>).cast<String, String>());
    }
  }

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) async {
    if (!kIsWeb && _cookies.isNotEmpty) {
      // "rdvmedecins_jwt=eyJhbGci...; other=value"
      request.headers['cookie'] = [for (final MapEntry(:key, :value) in _cookies.entries) '$key=$value'].join('; ');
    }
    final response = await _inner.send(request);
    final setCookie = response.headers['set-cookie'];
    if (!kIsWeb && setCookie != null) {
      _store(setCookie);
    }
    return response;
  }

  // Set-Cookie: rdvmedecins_jwt=eyJ...; Max-Age=7200; Path=/api; Expires=Tue, 29 Sep 2026 ...; HttpOnly
  // (vários cookies são separados por vírgulas). Guardamos apenas o
  // nome e o valor de cada cookie; um valor vazio (logout) o apaga
  void _store(String setCookie) {
    // um nome seguido de "=", no início do cabeçalho ou após uma vírgula
    for (final m in RegExp(r'(?:^|,)\s*([^=;,\s]+)=([^;]*)').allMatches(setCookie)) {
      final name = m[1]!;
      final value = m[2]!.trim();
      if (value.isEmpty) {
        _cookies.remove(name);
      } else {
        _cookies[name] = value;
      }
    }
    _storage?.setString(_key, jsonEncode(_cookies));
  }

  @override
  void close() => _inner.close();
}
  • Linha 25: o pacote [http] permite encapsular o seu cliente: você herda de [http.BaseClient] e só precisa implementar o método [send], por onde passam todas as requisições ([get], [post]...);
  • linhas 28–31: o cliente encapsulado, o armazenamento do dispositivo (opcional: [?]) e os cookies (nome → valor);
  • linhas 33–37: na criação, os cookies armazenados durante um uso anterior da aplicação. Isso mantém você logado quando fecha e reabre a aplicação: em um celular, equivale a um navegador que conserva seus cookies de uma visita para a outra;
  • linhas 42–52: cada requisição recebe o cabeçalho [Cookie] (“rdvmedecins_jwt=eyJhbGci...; other=value”) e, em seguida, o cabeçalho [Set-Cookie] da resposta é lido. [kIsWeb]: na web, a aplicação não faz nada além de um cliente comum, pois o navegador a impede de ler ou escrever esses cabeçalhos (ele cuida deles por conta própria);
  • linhas 58–69: o cabeçalho [Set-Cookie]. Vários cookies são separados por vírgulas, mas a data [Expires] em si contém uma vírgula (“Tue, 29 Sep 2026”): a expressão regular reconhece apenas um nome seguido de [=], seja no início do cabeçalho, seja depois de uma vírgula. Apenas o nome e o valor de cada cookie são mantidos; um valor vazio (logout: o servidor envia [rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970...]) exclui o cookie. [_storage?.setString(...)]: a chamada só é feita se [_storage] for diferente de [null].

Um gerenciamento de cookies mais completo (domínios, caminhos, datas de expiração) está disponível em pacotes ([cookie_jar], com o cliente [dio]); nossa implementação, de apenas algumas linhas, basta para UM servidor. Nota de segurança: aqui o token é armazenado em texto simples no dispositivo. Uma aplicação em produção usaria o pacote [flutter_secure_storage] (veja o exemplo 20).

9.2.2. Um comando

// =========================================================================
// lib/ex23_login/command.dart - uma AÇÃO, seu estado, seu resultado
// -------------------------------------------------------------------------
// Uma ação assíncrona (fazer login, salvar...) tem um estado que
// a tela deve mostrar: está EM ANDAMENTO (botão desabilitado, indicador)?
// terminou com um ERRO (mensagem)? É o padrão "Command"
// do guia de arquitetura do Flutter, reduzido ao essencial:
//
//     final login = Command();
//     login.execute(() => logIn(...));          // inicia a ação
//     login.running, login.error               // seu estado
//
// Um Command é um ChangeNotifier: a tela o escuta (ListenableBuilder)
// e se redesenha quando ele começa e quando termina.
// =========================================================================

import 'package:flutter/foundation.dart';

class Command extends ChangeNotifier {
  bool _running = false;
  Object? _error;

  bool get running => _running;
  Object? get error => _error;

  // executa a ação, se outra ainda não estiver em andamento
  Future<void> execute(Future<void> Function() action) async {
    if (_running) return; // sem envio duplo (toque duplo no botão)
    _running = true;
    _error = null;
    notifyListeners();
    try {
      await action();
    } catch (e) {
      _error = e; // o erro é MANTIDO, para ser exibido
    } finally {
      // finally: executado em TODOS os casos, sucesso ou erro
      _running = false;
      notifyListeners();
    }
  }

  void clearError() {
    _error = null;
    notifyListeners();
  }
}

Uma ação assíncrona (fazer login, salvar etc.) tem um estado que a tela precisa exibir: está em andamento (botão desabilitado)? Terminou com um erro (mensagem)? É o modelo “Command” do guia de arquitetura do [Flutter], reduzido ao essencial. O curso de [React] usava, para isso, as “actions” do [React] 19 ([useActionState]).

  • Linhas 27–39: executar uma ação: se outra ação estiver em andamento, não faz nada (para evitar envio duplo se o botão for pressionado duas vezes); caso contrário, o comando passa para “em andamento” e notifica seus listeners; em caso de exceção, o erro é registrado para exibição; em todos os casos ([finally]), o comando deixa de estar em andamento.

9.2.3. A tela

// =========================================================================
// lib/ex23_login/main.dart - login no servidor RdvMedecins
// -------------------------------------------------------------------------
//   1. na inicialização: GET /api/auth/me - já estamos logados?
//      (o aplicativo pode ter sido encerrado; o servidor, por sua vez, lê o cookie
//      que lhe é apresentado);
//   2. login: POST /api/auth/login, corpo JSON { login, password,
//      captchaId, captcha }. Em caso de sucesso, o servidor envia o cookie
//      do token JWT (cabeçalho Set-Cookie);
//   3. requisição protegida: GET /api/doctors. O cookie vai junto;
//   4. logout: POST /api/auth/logout - o servidor apaga o cookie.
// No celular, é o CookieClient (common/http_client.dart) que
// armazena o cookie e o reenvia; na web, é o navegador.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';

import '../common/http_client.dart';
import '../common/config.dart';
import 'command.dart';

// as poucas mensagens de que este exemplo precisa (o exemplo 25 usará dicionários)
const messages = {
  'LOGIN.ERROR': 'Incorrect login or password.',
  'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
  'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final client = CookieClient(await SharedPreferences.getInstance());
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: LoginPage(client: client),
    ),
  );
}

// uma resposta que não seja 2xx vira uma exceção, que guarda a resposta
class ErrorResponse implements Exception {
  final http.Response response;
  const ErrorResponse(this.response);
}

class LoginPage extends StatefulWidget {
  final http.Client client;

  const LoginPage({super.key, required this.client});

  @override
  State<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  Map<String, dynamic>? _user; // null: ninguém está logado
  List<dynamic> _doctors = [];
  Map<String, dynamic>? _captcha;
  bool _ready = false; // a verificação inicial terminou?
  String? _serverError;
  final _loginCommand = Command();
  final _login = TextEditingController(text: 'admin');
  final _password = TextEditingController();
  final _captchaAnswer = TextEditingController();

  @override
  void initState() {
    super.initState();
    _checkSession();
  }

  @override
  void dispose() {
    _loginCommand.dispose();
    _login.dispose();
    _password.dispose();
    _captchaAnswer.dispose();
    super.dispose();
  }

  Uri _url(String path) => Uri.parse('${Config.serverUrl}/api$path');

  // uma requisição GET cujo corpo JSON queremos; uma exceção se não for 2xx
  Future<dynamic> _read(String path) async {
    final response = await widget.client.get(_url(path));
    if (response.statusCode >= 300) throw ErrorResponse(response);
    return jsonDecode(utf8.decode(response.bodyBytes));
  }

  // um POST com corpo JSON
  Future<http.Response> _post(String path, Object body) {
    return widget.client.post(
      _url(path),
      headers: {'content-type': 'application/json'}, // o corpo é JSON
      body: jsonEncode(body),
    );
  }

  Future<void> _loadCaptcha() async {
    final captcha = await _read('/captcha') as Map<String, dynamic>;
    _captchaAnswer.clear();
    if (mounted) setState(() => _captcha = captcha);
  }

  Future<void> _loadDoctors() async {
    final doctors = await _read('/doctors') as List<dynamic>;
    if (mounted) setState(() => _doctors = doctors);
  }

  // 1. quem está logado? 200 -> o usuário; 401 -> ninguém
  Future<void> _checkSession() async {
    try {
      final user = await _read('/auth/me') as Map<String, dynamic>;
      setState(() => _user = user);
      await _loadDoctors();
    } on ErrorResponse catch (e) {
      // "on Type catch": captura SOMENTE este tipo de exceção
      if (e.response.statusCode == 401) {
        await _loadCaptcha();
      } else {
        _serverError = 'The server answered ${e.response.statusCode}.';
      }
    } catch (_) {
      _serverError = 'Is the RdvMedecins JSON server started (${Config.serverUrl})?';
    }
    if (mounted) setState(() => _ready = true);
  }

  // 2. o login: uma ação executada pelo Command, que guarda o seu erro
  Future<void> _logIn() async {
    final response = await _post('/auth/login', {
      'login': _login.text.trim(),
      'password': _password.text,
      'captchaId': _captcha?['id'],
      'captcha': _captchaAnswer.text,
    });
    if (response.statusCode != 200) {
      // o corpo JSON da resposta de erro: { statusCode, key, ... }
      final error = jsonDecode(response.body) as Map<String, dynamic>;
      final key = error['key'] as String;
      await _loadCaptcha(); // cada imagem só é usada uma vez
      throw '${response.statusCode} - ${messages[key] ?? key}'; // pode-se lançar... uma string
    }
    _password.clear();
    setState(() => _user = jsonDecode(response.body) as Map<String, dynamic>);
    await _loadDoctors();
  }

  // 4. o logout
  Future<void> _logOut() async {
    await _post('/auth/logout', {});
    setState(() {
      _user = null;
      _doctors = [];
    });
    await _loadCaptcha();
  }

  @override
  Widget build(BuildContext context) {
    final Widget content;
    final user = _user;
    if (!_ready) {
      content = const Text('Checking the session...', style: TextStyle(color: Colors.grey));
    } else if (user != null) {
      // logado
      content = Card(
        child: Padding(
          padding: const EdgeInsets.all(12),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text.rich(
                TextSpan(
                  children: [
                    const TextSpan(text: 'Logged in: '),
                    TextSpan(
                      text: '${user['name']}',
                      style: const TextStyle(fontWeight: FontWeight.bold),
                    ),
                    TextSpan(text: ' (${user['login']}), role ${user['role']}'),
                  ],
                ),
              ),
              const SizedBox(height: 8),
              Text('GET /api/doctors', style: Theme.of(context).textTheme.titleSmall),
              for (final m in _doctors) Text('• ${m['title']} ${m['firstName']} ${m['lastName']}'),
              const SizedBox(height: 8),
              const Text(
                'Stop then restart the application: you remain logged in.',
                style: TextStyle(color: Colors.grey),
              ),
              const SizedBox(height: 8),
              OutlinedButton(onPressed: _logOut, child: const Text('Log out')),
            ],
          ),
        ),
      );
    } else if (_serverError == null) {
      // não logado: o formulário
      content = Card(
        child: Padding(
          padding: const EdgeInsets.all(12),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              TextField(
                controller: _login,
                decoration: const InputDecoration(labelText: 'Login'),
              ),
              TextField(
                controller: _password,
                obscureText: true,
                decoration: const InputDecoration(labelText: 'Password'),
              ),
              const SizedBox(height: 12),
              Row(
                children: [
                  if (_captcha != null) SvgPicture.string('${_captcha!['svg']}', height: 50),
                  TextButton(onPressed: _loadCaptcha, child: const Text('Another image')),
                ],
              ),
              TextField(
                controller: _captchaAnswer,
                autocorrect: false,
                decoration: const InputDecoration(labelText: 'Type the characters of the image'),
              ),
              const SizedBox(height: 16),
              // ListenableBuilder: este trecho acompanha o estado do command
              ListenableBuilder(
                listenable: _loginCommand,
                builder: (context, _) => Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    FilledButton(
                      onPressed: _loginCommand.running ? null : () => _loginCommand.execute(_logIn),
                      child: Text(_loginCommand.running ? 'Logging in...' : 'Log in'),
                    ),
                    if (_loginCommand.error != null)
                      Padding(
                        padding: const EdgeInsets.only(top: 12),
                        child: Text('${_loginCommand.error}', style: const TextStyle(color: Colors.red)),
                      ),
                  ],
                ),
              ),
              const SizedBox(height: 8),
              const Text(
                'Accounts: admin, pelissier, martin... (password = login).',
                style: TextStyle(color: Colors.grey, fontSize: 12),
              ),
            ],
          ),
        ),
      );
    } else {
      content = const SizedBox.shrink(); // um widget "vazio"
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Example 23 - logging in to the server')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          content,
          if (_serverError != null)
            Card(
              color: Colors.red.shade50,
              child: Padding(padding: const EdgeInsets.all(12), child: Text(_serverError!)),
            ),
        ],
      ),
    );
  }
}
  • linhas 36–41: o cliente HTTP, que armazena seus cookies no dispositivo, é criado na inicialização e passado à tela;
  • linhas 47–49: uma exceção que captura a resposta como um erro (seu código de status pode ser lido ali). [implements Exception]: um objeto que pode ser lançado ([throw]);
  • linhas 90–93: uma requisição (GET) da qual queremos o corpo (JSON), e uma exceção se o código de status não for 2xx. [widget.client.get(...)]: o cliente com cookies. [utf8.decode(response.bodyBytes)]: o corpo decodificado em UTF-8 (os acentos), independentemente do que diga o cabeçalho da resposta;
  • linhas 97–101: um POST: o cabeçalho é [content-type: application/json] e o corpo está em JSON (o servidor rejeita um POST que não esteja em JSON);
  • Linhas 117–132: 1. Na inicialização: quem está conectado? [GET /api/auth/me]: 200, o usuário; 401, ninguém. [on ErrorResponse catch (e)] captura SOMENTE esse tipo de exceção; o [catch] seguinte, todas as outras (nenhuma resposta);
  • linhas 136–152: 2. login: [POST /api/auth/login]. Se a requisição for rejeitada, o corpo da resposta de erro fornece a chave da mensagem; uma nova imagem é carregada (cada uma é usada apenas uma vez) e, então, a mensagem é lançada: em [Dart], qualquer objeto pode ser lançado — neste caso, uma string. É o comando que a captura e a armazena;
  • linhas 156–162: 4. Logout: [POST /api/auth/logout]; o servidor exclui o cookie (e o cliente também exclui os seus);
  • linhas 193–197: 3. logado: a lista de médicos ([GET /api/doctors], uma requisição protegida: o cookie a acompanha);
  • linhas 225–226: o CAPTCHA e seu botão;
  • linhas 236–248: o botão reflete o estado da requisição: desabilitado e com “Entrando...” enquanto a requisição é enviada; qualquer mensagem de erro aparece abaixo.

A tela de login; uma senha incorreta; login bem-sucedido:

Feche e reinicie a aplicação: ela iniciará já logada. O cookie, armazenado no dispositivo, é apresentado a [GET /api/auth/me], e o servidor responde com as credenciais do usuário. O token expira após duas horas: [GET /api/auth/me] passará então a devolver uma resposta 401, e a tela de login reaparecerá.

9.3. Exemplo 24: uma camada de acesso à API

No exemplo 23, cada requisição repetia as mesmas etapas. Este exemplo as organiza em três camadas, que o estudo de caso retomará.

9.3.1. Os tipos

// =========================================================================
// lib/common/types.dart - os objetos JSON trocados com a API RdvMedecins
// (veja o capítulo sobre a caixa-preta, que descreve cada rota)
// -------------------------------------------------------------------------
// O JSON decodificado não é tipado: Map<String, dynamic>, List...
// Cada classe tem um construtor "factory" fromJson que VERIFICA o formato
// do JSON recebido, com o "pattern matching" do Dart 3:
//
//   switch (json) {
//     {'login': String login, 'name': String name} => ...   // o formato esperado
//     _ => throw FormatException(...)                       // todo o resto
//   }
//
// O padrão {'login': String login, ...} verifica que json é um Map, que
// estas chaves existem, que seus valores têm o tipo certo, e armazena estes
// valores em variáveis. Uma resposta inesperada é detectada
// imediatamente, e não depois, no meio da exibição.
// =========================================================================

enum Role { admin, doctor, user }

// "ADMIN" -> Role.admin
Role _role(String name) => Role.values.byName(name.toLowerCase());

// POST /api/auth/login, GET /api/auth/me
class User {
  final String login;
  final String name;
  final Role role;

  const User(this.login, this.name, this.role);

  factory User.fromJson(Object? json) => switch (json) {
    {'login': final String login, 'name': final String name, 'role': final String role} => User(
      login,
      name,
      _role(role),
    ),
    _ => throw FormatException('unexpected User: $json'),
  };
}

// GET /api/captcha
class Captcha {
  final String id;
  final String svg;

  const Captcha(this.id, this.svg);

  factory Captcha.fromJson(Object? json) => switch (json) {
    {'id': final String id, 'svg': final String svg} => Captcha(id, svg),
    _ => throw FormatException('unexpected Captcha: $json'),
  };
}

// um médico ou um cliente (GET /api/doctors, GET /api/clients...)
class Person {
  final int id;
  final int version;
  final String title;
  final String firstName;
  final String lastName;
  final String? login; // somente para o ADMIN

  const Person(this.id, this.version, this.title, this.firstName, this.lastName, [this.login]);

  factory Person.fromJson(Object? json) => switch (json) {
    {
      'id': final int id,
      'version': final int version,
      'title': final String title,
      'firstName': final String firstName,
      'lastName': final String lastName,
    } =>
      // a chave "login" é opcional: ela é lida separadamente
      Person(id, version, title, firstName, lastName, (json as Map<String, Object?>)['login'] as String?),
    _ => throw FormatException('unexpected Person: $json'),
  };

  // uma lista JSON -> uma lista de pessoas
  static List<Person> list(Object? json) => [for (final p in json as List<Object?>) Person.fromJson(p)];

  String get fullName => '$title $firstName $lastName';
}

// o nome de uma pessoa, e nada mais
class Identity {
  final String title;
  final String firstName;
  final String lastName;

  const Identity(this.title, this.firstName, this.lastName);

  factory Identity.fromJson(Object? json) => switch (json) {
    {'title': final String title, 'firstName': final String firstName, 'lastName': final String lastName} => Identity(
      title,
      firstName,
      lastName,
    ),
    _ => throw FormatException('unexpected Identity: $json'),
  };

  @override
  String toString() => '$title $firstName $lastName';
}

// uma linha de GET /api/schedule
class ScheduleSlot {
  final int id;
  final int startHour;
  final int startMinute;
  final int endHour;
  final int endMinute;
  final bool free;
  final Identity? patient;
  final bool mine;
  final bool bookable;
  final int? appointmentId;

  const ScheduleSlot(
    this.id,
    this.startHour,
    this.startMinute,
    this.endHour,
    this.endMinute,
    this.free,
    this.patient,
    this.mine,
    this.bookable,
    this.appointmentId,
  );

  factory ScheduleSlot.fromJson(Object? json) => switch (json) {
    {
      'id': final int id,
      'startHour': final int startHour,
      'startMinute': final int startMinute,
      'endHour': final int endHour,
      'endMinute': final int endMinute,
      'free': final bool free,
      'patient': final Object? patient,
      'mine': final bool mine,
      'bookable': final bool bookable,
      'appointmentId': final int? appointmentId,
    } =>
      ScheduleSlot(
        id,
        startHour,
        startMinute,
        endHour,
        endMinute,
        free,
        patient == null ? null : Identity.fromJson(patient),
        mine,
        bookable,
        appointmentId,
      ),
    _ => throw FormatException('unexpected ScheduleSlot: $json'),
  };

  // "8:00 - 8:20"
  String get timeRange {
    String hm(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';
    return '${hm(startHour, startMinute)} - ${hm(endHour, endMinute)}';
  }
}

// GET /api/schedule?doctorId=...&day=...
class Schedule {
  final Person doctor;
  final String day;
  final List<ScheduleSlot> slots;
  final String? info;

  const Schedule(this.doctor, this.day, this.slots, this.info);

  factory Schedule.fromJson(Object? json) => switch (json) {
    {
      'doctor': final Object doctor,
      'day': final String day,
      'slots': final List<Object?> slots,
      'info': final String? info,
    } =>
      Schedule(Person.fromJson(doctor), day, [for (final c in slots) ScheduleSlot.fromJson(c)], info),
    _ => throw FormatException('unexpected Schedule: $json'),
  };
}

O JSON decodificado não tem tipo: [Map], [List], [dynamic]. Cada classe tem um construtor factory [fromJson] que valida o formato do JSON recebido. Um construtor [factory] não cria necessariamente um novo objeto: é uma função que devolve um objeto da classe.

  • Linhas 33–39: [Dart] 3, pattern matching aplicado ao JSON. O padrão [{'login': final String login, 'name': final String name, 'role': final String role}] verifica se [json] é um [Map], se essas três chaves existem, se seus valores são strings, e armazena esses valores em três variáveis. Se o JSON tiver um formato diferente, como é o caso com [_], ele é tratado como uma exceção. Uma resposta inesperada é assim detectada assim que é recebida, e não mais tarde, no meio da exibição;
  • linha 23: “ADMIN” -> [Role.admin]: [byName] recupera um valor de enumeração pelo seu nome;
  • linhas 67–76: o padrão verifica as chaves obrigatórias; a chave opcional [login] é lida separadamente;
  • linha 81: um JSON de lista -> uma lista de pessoas;
  • linhas 133–144: [final Object? patient] aceita qualquer valor, inclusive [null]; [final int? appointmentId], um inteiro, ou [null];
  • linhas 162–164: um getter de formatação.

9.3.2. Erros

// =========================================================================
// lib/common/api_error.dart - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Todas as respostas de erro do servidor RdvMedecins têm o mesmo formato:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Mas uma requisição também pode falhar de OUTRO modo: nenhuma resposta
// (rede fora do ar, servidor parado, endereço errado), ou uma resposta que não
// vem do nosso servidor (uma página de erro de um proxy). Convertemos
// tudo isso em UMA só classe, ApiError, que carrega a chave de tradução
// enviada pelo servidor (e, se houver, seus parâmetros e o erro de
// cada campo).
// =========================================================================

import 'dart:convert';

import 'package:http/http.dart' as http;

// "implements Exception": um objeto que pode ser lançado (throw) e capturado (catch)
class ApiError implements Exception {
  final int statusCode; // 0: o servidor não respondeu
  final String key; // p. ex. 'ERRORS.LOGIN_TAKEN'
  final Map<String, String> params;
  final Map<String, String> fields;

  const ApiError(this.statusCode, this.key, {this.params = const {}, this.fields = const {}});

  // uma resposta de erro (4xx, 5xx) -> um ApiError
  factory ApiError.fromResponse(http.Response response) {
    Object? body;
    try {
      body = jsonDecode(utf8.decode(response.bodyBytes));
    } on FormatException {
      body = null; // não é JSON: não foi o nosso servidor que respondeu
    }
    // o "pattern matching" de um Map: se o corpo tem uma chave
    // "key" do tipo String, ela é armazenada na variável key
    if (body case {'key': final String key}) {
      final json = body as Map<String, Object?>;
      return ApiError(response.statusCode, key, params: _strings(json['params']), fields: _strings(json['fields']));
    }
    // sem key: foi o proxy ou a rede que respondeu no lugar
    return ApiError(
      response.statusCode,
      response.statusCode >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }

  // um objeto JSON { "name": "ERRORS..." } -> Map<String, String> (vazio caso contrário)
  static Map<String, String> _strings(Object? json) =>
      json is Map<String, Object?> ? {for (final e in json.entries) e.key: '${e.value}'} : const {};

  @override
  String toString() => '$statusCode $key';
}

Todas as respostas de erro do servidor têm o mesmo formato. No entanto, uma requisição também pode falhar DE OUTRO MODO: nenhuma resposta, ou uma resposta que não vem do nosso servidor. Convertemos tudo isso em UMA só classe, [ApiError].

  • linhas 19–23: um status (0: nenhuma resposta), uma chave de tradução, seus parâmetros e o erro de cada campo;
  • linhas 28–44: uma resposta de erro → um [ApiError]. [if (body case {'key': final String key})]: filtragem em um [if] (“if-case”): se o corpo tiver uma chave [key] do tipo string, ela é armazenada na variável [key]. Caso contrário, não foi o nosso servidor que respondeu;
  • linha 53: “401 LOGIN.ERROR”, para exibição rápida.

9.3.3. As requisições

// =========================================================================
// lib/common/api.dart - requisições à API, em uma linha
// -------------------------------------------------------------------------
// No exemplo 23, cada requisição repetia as mesmas etapas: endereço do
// servidor, prefixo /api, cabeçalho JSON, teste do código de status, leitura do
// corpo do erro... Elas são reunidas aqui:
//
//   final json = await api.get('/doctors');
//   await api.post('/appointments', {'day': day, 'slotId': 3});
//
//   - em caso de sucesso, o Future retorna o corpo JSON, DECODIFICADO (Maps,
//     Lists, Strings, números...);
//   - em caso de falha, ele é concluído com um ApiError.
// Todas as requisições passam pelo método request: é o lugar onde
// um problema COMUM a todas elas seria tratado (veja o estudo de caso e a
// resposta 401). Usado pelos exemplos 24 e 25.
// =========================================================================

import 'dart:convert';

import 'package:http/http.dart' as http;

import 'config.dart';
import 'api_error.dart';

class Api {
  final http.Client _client;

  Api(this._client);

  Future<Object?> request(String method, String url, [Object? body]) async {
    final request = http.Request(method, Uri.parse('${Config.serverUrl}/api$url'));
    if (body != null) {
      // um corpo JSON (o servidor recusa um POST que não tenha um)
      request.headers['content-type'] = 'application/json';
      request.body = jsonEncode(body);
    }
    final http.Response response;
    try {
      // send envia a requisição; fromStream espera o corpo completo da resposta
      response = await http.Response.fromStream(await _client.send(request));
    } catch (_) {
      // NENHUMA resposta (rede, servidor parado, endereço errado)
      throw const ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    if (response.statusCode >= 400) {
      throw ApiError.fromResponse(response);
    }
    return response.bodyBytes.isEmpty ? null : jsonDecode(utf8.decode(response.bodyBytes));
  }

  Future<Object?> get(String url) => request('GET', url);
  // um POST sempre tem um corpo JSON: {} por padrão
  Future<Object?> post(String url, [Object body = const {}]) => request('POST', url, body);
  Future<Object?> put(String url, Object body) => request('PUT', url, body);
  Future<Object?> delete(String url, [Object? body]) => request('DELETE', url, body);
}
  • Linhas 31–49: TODAS as requisições passam por este método: o endereço do servidor e o prefixo [/api], o corpo em JSON, o envio ([_client.send], seguido de [http.Response.fromStream], que espera o corpo completo), os erros convertidos em [ApiError] e o corpo da resposta decodificado. É aqui que trataríamos um problema comum a todas as requisições (veja o estudo de caso e a resposta 401);
  • linhas 52–56: quatro atalhos. Um POST sempre tem um corpo em JSON: [{}] por padrão.

9.3.4. Uma barra de login

// =========================================================================
// lib/common/login_bar.dart - login / logout, em uma barra
// -------------------------------------------------------------------------
// O formulário do exemplo 23, reduzido a uma barra e reescrito com api.dart.
// O widget chama onUserChange com o usuário logado (ou
// null) a cada vez que ele muda - inclusive na inicialização, depois de
// consultar GET /api/auth/me. O objeto Api é lido no contexto
// (fornecido pelo provider, veja o main dos exemplos 24 e 25).
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';
import 'package:provider/provider.dart';

import 'api.dart';
import 'api_error.dart';
import 'types.dart';

class LoginBar extends StatefulWidget {
  final ValueChanged<User?> onUserChange;

  const LoginBar({super.key, required this.onUserChange});

  @override
  State<LoginBar> createState() => _LoginBarState();
}

class _LoginBarState extends State<LoginBar> {
  // late: lido no contexto, em initState
  late final Api _api = context.read<Api>();
  User? _user;
  Captcha? _captcha;
  final _login = TextEditingController(text: 'admin');
  final _password = TextEditingController();
  final _captchaAnswer = TextEditingController();
  String? _error;

  @override
  void initState() {
    super.initState();
    _start();
  }

  @override
  void dispose() {
    _login.dispose();
    _password.dispose();
    _captchaAnswer.dispose();
    super.dispose();
  }

  void _setUser(User? u) {
    setState(() => _user = u);
    widget.onUserChange(u);
  }

  Future<void> _newCaptcha() async {
    final captcha = Captcha.fromJson(await _api.get('/captcha'));
    _captchaAnswer.clear();
    if (mounted) setState(() => _captcha = captcha);
  }

  // na inicialização: já estamos logados?
  Future<void> _start() async {
    try {
      _setUser(User.fromJson(await _api.get('/auth/me')));
    } on ApiError {
      _setUser(null); // 401: ninguém está logado
      try {
        await _newCaptcha();
      } on ApiError {
        setState(() => _error = 'Is the JSON server started (port 8080)?');
      }
    }
  }

  Future<void> _logIn() async {
    setState(() => _error = null);
    try {
      final u = User.fromJson(
        await _api.post('/auth/login', {
          'login': _login.text.trim(),
          'password': _password.text,
          'captchaId': _captcha?.id,
          'captcha': _captchaAnswer.text,
        }),
      );
      _password.clear();
      _setUser(u);
    } on ApiError catch (e) {
      setState(() => _error = '$e'); // "401 LOGIN.ERROR"
      await _newCaptcha();
    }
  }

  Future<void> _logOut() async {
    await _api.post('/auth/logout');
    _setUser(null);
    await _newCaptcha();
  }

  @override
  Widget build(BuildContext context) {
    final u = _user;
    return Card(
      color: Colors.blueGrey.shade50,
      child: Padding(
        padding: const EdgeInsets.all(8),
        child: u != null
            ? Row(
                children: [
                  const Icon(Icons.person),
                  const SizedBox(width: 8),
                  Expanded(child: Text('${u.name} (${u.role.name.toUpperCase()})')),
                  TextButton(onPressed: _logOut, child: const Text('Log out')),
                ],
              )
            : Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Row(
                    children: [
                      Expanded(
                        child: TextField(
                          controller: _login,
                          decoration: const InputDecoration(labelText: 'login', isDense: true),
                        ),
                      ),
                      const SizedBox(width: 8),
                      Expanded(
                        child: TextField(
                          controller: _password,
                          obscureText: true,
                          decoration: const InputDecoration(labelText: 'password', isDense: true),
                        ),
                      ),
                    ],
                  ),
                  Row(
                    children: [
                      // a imagem SVG do captcha, produzida pelo NOSSO servidor (veja o exemplo 22)
                      if (_captcha != null) SvgPicture.string(_captcha!.svg, height: 40),
                      const SizedBox(width: 8),
                      Expanded(
                        child: TextField(
                          controller: _captchaAnswer,
                          autocorrect: false,
                          decoration: const InputDecoration(labelText: 'captcha', isDense: true),
                        ),
                      ),
                      IconButton(tooltip: 'Log in', icon: const Icon(Icons.login), onPressed: _logIn),
                    ],
                  ),
                  if (_error != null) Text(_error!, style: const TextStyle(color: Colors.red)),
                ],
              ),
      ),
    );
  }
}

O formulário do exemplo 23, reduzido a uma única barra e reescrito com o uso de [Api]. Ele chama [onUserChange] sempre que o usuário logado muda, inclusive na inicialização.

  • Linha 30: o objeto [Api] é fornecido anteriormente (por [provider]); [late]: ele só é lido no primeiro uso, em [initState];
  • Linhas 64–72: na inicialização, quem está conectado? [User.fromJson(await _api.get('/auth/me'))]: uma linha. Qualquer [ApiError] significa “ninguém”;
  • linhas 77–92: o login, em poucas linhas: os erros aparecem como [ApiError].

9.3.5. A camada de acesso à API

// =========================================================================
// lib/ex24_api_layer/rdvmedecins.dart - a camada de acesso à API
// -------------------------------------------------------------------------
// Um método tipado por rota da API. As telas não conhecem nem as
// URLs, nem o pacote http, nem o formato JSON: elas chamam métodos
// que retornam objetos Dart (Person, Schedule...).
// É o equivalente, no lado do cliente, da camada DAO do lado do servidor: se a API
// mudar (uma URL, o nome de um campo), só este arquivo é modificado.
// No guia de arquitetura do Flutter, é um "repository".
// =========================================================================

import '../common/api.dart';
import '../common/types.dart';

class RdvMedecins {
  final Api _api;

  RdvMedecins(this._api);

  Future<List<Person>> getDoctors() async => Person.list(await _api.get('/doctors'));

  Future<List<Person>> getClients() async => Person.list(await _api.get('/clients'));

  // Uri monta "doctorId=1&day=2030-01-15", codificando o que for necessário
  Future<Schedule> getSchedule(int doctorId, String day) async {
    final params = Uri(queryParameters: {'doctorId': '$doctorId', 'day': day}).query;
    return Schedule.fromJson(await _api.get('/schedule?$params'));
  }

  // [int? clientId]: um parâmetro opcional. '?clientId' no Map: a chave
  // só é colocada no Map se clientId não for null (Dart 3.8)
  Future<void> book(String day, int slotId, [int? clientId]) =>
      _api.post('/appointments', {'day': day, 'slotId': slotId, 'clientId': ?clientId});

  Future<void> cancelAppointment(int appointmentId) => _api.delete('/appointments/$appointmentId');
}

Um método por rota da API, tipado. As telas desconhecem os endereços, o pacote [http] ou o formato JSON: elas chamam métodos que devolvem objetos [Dart]. Se a API mudar (um endereço, o nome de um campo), apenas este arquivo é modificado. O guia de arquitetura do [Flutter] chama essa camada de “repositório”.

  • Linha 26: [Uri] constrói a string “doctorId=1&day=2030-01-15”, codificando os dados necessários;
  • linha 33: ['clientId': ?clientId] dentro de um literal [Map]: a chave é colocada no [Map] somente se [clientId] não for [null] (os “elementos opcionais” do [Dart] 3.8).

9.3.6. A view model

// =========================================================================
// lib/ex24_api_layer/schedule_model.dart - o "view model" da tela
// -------------------------------------------------------------------------
// O guia de arquitetura do Flutter recomenda separar:
//   - a VIEW: os widgets, que exibem e repassam as ações do
//     usuário;
//   - o VIEW MODEL (ViewModel): um ChangeNotifier que mantém o estado
//     da tela (o médico escolhido, o dia, a agenda recebida...), as ações
//     (escolher, marcar, cancelar), e que chama a camada de acesso à
//     API.
// A view não tem mais nenhuma lógica: é simples de ler; o view model
// não tem widgets: é simples de testar.
//
// Ele também faz o que não queremos reescrever em cada tela:
//   - um CACHE: a agenda de cada (médico, dia) já lida é mantida; voltar
//     a ela a exibe na hora, enquanto é lida de novo em segundo plano;
//   - as respostas ANTIGAS são ignoradas (veja o exemplo 19).
// =========================================================================

import 'package:flutter/foundation.dart';

import '../common/api_error.dart';
import '../common/types.dart';
import 'rdvmedecins.dart';

String _twoDigits(int n) => n.toString().padLeft(2, '0');
String formatDay(DateTime d) => '${d.year}-${_twoDigits(d.month)}-${_twoDigits(d.day)}';

class ScheduleModel extends ChangeNotifier {
  final RdvMedecins _rdvmedecins;

  ScheduleModel(this._rdvmedecins);

  // o estado
  User? user;
  List<Person> doctors = [];
  List<Person> clients = [];
  int? doctorId;
  String day = formatDay(DateTime.now().add(const Duration(days: 1))); // amanhã
  int? clientId;
  Schedule? schedule;
  bool loading = false;
  ({bool success, String text})? message;

  final Map<String, Schedule> _cache = {};
  int _readNumber = 0;

  // valores calculados
  bool get loggedIn => user != null;
  bool get isManager => loggedIn && user!.role != Role.user;

  // as ações
  Future<void> changeUser(User? u) async {
    user = u;
    doctors = [];
    clients = [];
    schedule = null;
    doctorId = null;
    _cache.clear(); // os direitos mudaram: tudo é esquecido
    notifyListeners();
    if (u == null) return;
    doctors = await _rdvmedecins.getDoctors();
    if (isManager) clients = await _rdvmedecins.getClients(); // um USER receberia 403
    notifyListeners();
  }

  void chooseDoctor(int id) {
    doctorId = id;
    message = null;
    _readSchedule();
  }

  void chooseDay(DateTime d) {
    day = formatDay(d);
    message = null;
    _readSchedule();
  }

  void chooseClient(int? id) {
    clientId = id;
    notifyListeners();
  }

  Future<void> book(ScheduleSlot c) =>
      _act(() => _rdvmedecins.book(day, c.id, isManager ? clientId : null), 'Slot ${c.timeRange} booked.');

  Future<void> cancel(ScheduleSlot c) =>
      _act(() => _rdvmedecins.cancelAppointment(c.appointmentId!), 'Appointment of ${c.timeRange} cancelled.');

  // uma ação, e SEMPRE uma nova leitura da agenda: o SERVIDOR é a referência
  Future<void> _act(Future<void> Function() action, String success) async {
    try {
      await action();
      message = (success: true, text: success);
    } on ApiError catch (e) {
      message = (success: false, text: '$e');
    }
    await _readSchedule();
  }

  Future<void> _readSchedule() async {
    final id = doctorId;
    if (id == null) return;
    final key = '$id/$day';
    final number = ++_readNumber;
    // primeiro o cache (ou nada), depois a leitura
    schedule = _cache[key];
    loading = true;
    notifyListeners();
    try {
      final fetched = await _rdvmedecins.getSchedule(id, day);
      if (number != _readNumber) return; // uma leitura mais recente foi iniciada
      schedule = _cache[key] = fetched;
    } on ApiError catch (e) {
      if (number != _readNumber) return;
      schedule = null;
      message = (success: false, text: '$e');
    }
    loading = false;
    notifyListeners();
  }
}

O guia de arquitetura do [Flutter] recomenda separar a view (os widgets, que exibem e transmitem as ações do usuário) e a view model (um [ChangeNotifier] que contém o estado da tela e suas ações, e que chama a camada de acesso à API). A view não contém mais nenhuma lógica; a view model não tem widgets: pode ser testada sem uma tela.

  • linhas 35–43: o estado da tela;
  • linhas 45–46: um cache: a agenda de cada (médico, dia) que já foi lida é armazenada; ao voltar a ela, ela é exibida imediatamente enquanto é relida. E o número da última leitura, para ignorar respostas desatualizadas (veja o exemplo 19). Isso, em poucas linhas, é o que a biblioteca [TanStack Query] do curso de [React] faz;
  • linhas 49–50: valores calculados;
  • linhas 53–64: um novo usuário: limpamos tudo (as permissões mudaram) e, então, lemos os médicos e, para ADMIN e DOCTOR, os clientes (um USER receberia um 403);
  • linhas 91–98: uma ação (reservar, cancelar) e, em seguida, SEMPRE uma nova leitura da agenda: a resposta do servidor tem precedência;
  • linhas 101–120: a recuperação da agenda: primeiro do cache (ou nada), depois a resposta do servidor, a menos que uma recuperação mais recente tenha sido iniciada nesse meio-tempo.

9.3.7. A tela

// =========================================================================
// lib/ex24_api_layer/main.dart - uma agenda, com a camada de acesso à API
// -------------------------------------------------------------------------
// Faça login (barra superior), escolha um médico e um dia:
// a agenda é exibida. ADMIN e DOCTOR podem marcar consultas para um paciente e
// cancelá-las; um paciente (martin...) marca para si mesmo. Cada ação
// termina com uma nova leitura da agenda.
// Três camadas, de baixo para cima:
//   Api (common/api.dart)          as requisições HTTP, os erros;
//   RdvMedecins (rdvmedecins.dart) um método tipado por rota da API;
//   ScheduleModel (schedule_model.dart) o estado e as ações da tela;
// e a view, abaixo, que apenas exibe o model.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import '../common/api.dart';
import '../common/login_bar.dart';
import '../common/http_client.dart';
import '../common/types.dart';
import 'schedule_model.dart';
import 'rdvmedecins.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final api = Api(CookieClient(await SharedPreferences.getInstance()));
  runApp(
    MultiProvider(
      providers: [
        // Provider: fornece um objeto comum (que não notifica nada)
        Provider.value(value: api),
        ChangeNotifierProvider(create: (_) => ScheduleModel(RdvMedecins(api))),
      ],
      child: MaterialApp(
        debugShowCheckedModeBanner: false,
        theme: ThemeData(colorSchemeSeed: Colors.indigo),
        home: const SchedulePage(),
      ),
    ),
  );
}

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

  @override
  Widget build(BuildContext context) {
    final model = context.watch<ScheduleModel>();
    final schedule = model.schedule;
    final message = model.message;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 24 - an API access layer')),
      body: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          LoginBar(onUserChange: model.changeUser),
          if (model.loggedIn) ...[
            DropdownButton<int>(
              isExpanded: true,
              hint: const Text('-- choose a doctor --'),
              value: model.doctorId,
              items: [for (final m in model.doctors) DropdownMenuItem(value: m.id, child: Text(m.fullName))],
              onChanged: (id) => model.chooseDoctor(id!),
            ),
            Row(
              children: [
                Text('Day: ${model.day}'),
                IconButton(
                  icon: const Icon(Icons.calendar_month),
                  onPressed: () async {
                    final d = await showDatePicker(
                      context: context,
                      initialDate: DateTime.parse(model.day),
                      firstDate: DateTime(2020),
                      lastDate: DateTime(2035),
                    );
                    if (d != null) model.chooseDay(d);
                  },
                ),
              ],
            ),
            if (model.isManager)
              DropdownButton<int?>(
                isExpanded: true,
                value: model.clientId,
                items: [
                  const DropdownMenuItem(value: null, child: Text('-- patient to book for --')),
                  for (final c in model.clients) DropdownMenuItem(value: c.id, child: Text(c.fullName)),
                ],
                onChanged: model.chooseClient,
              ),
            if (message != null)
              Card(
                color: message.success ? Colors.green.shade50 : Colors.red.shade50,
                child: Padding(padding: const EdgeInsets.all(10), child: Text(message.text)),
              ),
            if (model.loading) const LinearProgressIndicator(),
            if (schedule != null) ...[
              // info: a chave enviada pelo servidor quando um paciente já tem uma consulta futura
              if (schedule.info != null) Text(schedule.info!, style: const TextStyle(color: Colors.blue)),
              Padding(
                padding: const EdgeInsets.symmetric(vertical: 8),
                child: Text(
                  'Schedule of ${schedule.day} - ${schedule.doctor.fullName}',
                  style: Theme.of(context).textTheme.titleSmall,
                ),
              ),
              for (final c in schedule.slots) _SlotRow(slot: c),
            ],
          ],
        ],
      ),
    );
  }
}

// uma linha da agenda: o intervalo de horário, o ocupante, os botões permitidos
class _SlotRow extends StatelessWidget {
  final ScheduleSlot slot;

  const _SlotRow({required this.slot});

  @override
  Widget build(BuildContext context) {
    final c = slot;
    final model = context.read<ScheduleModel>();
    final Widget status = c.free
        ? Chip(label: const Text('Free'), backgroundColor: Colors.green.shade100)
        : Chip(
            label: Text(c.patient?.toString() ?? 'Booked'),
            backgroundColor: c.mine ? Colors.indigo.shade100 : Colors.grey.shade300,
          );
    return ListTile(
      dense: true,
      contentPadding: EdgeInsets.zero,
      leading: SizedBox(width: 90, child: Text(c.timeRange)),
      title: Align(alignment: Alignment.centerLeft, child: status),
      // os botões seguem os direitos calculados pelo servidor
      trailing: c.bookable
          ? IconButton(
              tooltip: 'Book',
              icon: const Icon(Icons.add_circle_outline, color: Colors.green),
              onPressed: () => model.book(c),
            )
          : c.appointmentId != null
          ? IconButton(
              tooltip: 'Cancel',
              icon: const Icon(Icons.cancel_outlined, color: Colors.red),
              onPressed: () => model.cancel(c),
            )
          : null,
    );
  }
}
  • linhas 28–34: as três camadas, montadas na inicialização: [Api] (as requisições), [RdvMedecins] (as rotas), [ScheduleModel] (a tela). [Provider.value] fornece um objeto comum, que não dispara nenhuma notificação;
  • linha 50: a view assina a view model;
  • linha 58: a barra de login notifica o modelo;
  • o resto é apenas exibição: cada widget lê o estado do modelo e, quando o usuário age, chama um de seus métodos ([model.chooseDoctor(id!)], [model.book(c)]...);
  • linhas 120–153: uma linha da agenda. Os botões seguem as permissões calculadas pelo servidor ([bookable], [appointmentId]).

Logado como [admin], a agenda da Dra. PELISSIER; um horário é reservado para um paciente; logado como [martin] (papel USER), a mesma agenda:

O paciente [martin] não consegue ver o nome do paciente do horário reservado: o servidor não o enviou a ele.

9.4. Exemplo 25: erros devolvidos pelo servidor

9.4.1. Os dicionários

{
  "FORM": {
    "TITLE_ADD": "Ajouter un client",
    "TITLE_EDIT": "Modifier un client",
    "TITLE": "Titre",
    "FIRSTNAME": "Prénom",
    "LASTNAME": "Nom",
    "LOGIN": "Login",
    "PASSWORD": "Mot de passe",
    "SAVE": "Enregistrer",
    "CANCEL": "Annuler",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "DELETE_CONFIRM": "Supprimer le client {{name}}, son compte et ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé.",
    "ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients.",
    "PAGE_TITLE": "Exemple 25 - les erreurs du serveur",
    "NEW": "Nouveau client"
  },
  "ERRORS": {
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
    "FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
    "AUTH_REQUIRED": "Connectez-vous d'abord.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite.",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image."
  }
}

As mensagens de erro do servidor são chaves (“ERRORS.LASTNAME_REQUIRED”): o dicionário as traduz.

9.4.2. A tela

// =========================================================================
// lib/ex25_server_errors/main.dart - exibição dos erros do SERVIDOR
// -------------------------------------------------------------------------
// A gestão dos clientes (conta admin). Este formulário não faz,
// DELIBERADAMENTE, nenhuma validação no celular: tudo é enviado ao
// servidor, que responde, em caso de recusa, com um erro JSON (convertido em
// ApiError por common/api.dart):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (bloqueio otimista)
//
// O erro de CADA campo (ApiError.fields) é armazenado no estado e
// exibido abaixo do campo (errorText); sua mensagem é a CHAVE enviada pelo
// servidor, que a tela traduz (dicionários do exemplo 21).
// Modificar um campo apaga o seu erro.
// Experimente: um sobrenome vazio, um título "Dr", um homônimo (Alice DURAND), um
// login já em uso (martin), o mesmo registro modificado em dois dispositivos...
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import '../common/api.dart';
import '../common/login_bar.dart';
import '../common/http_client.dart';
import '../common/api_error.dart';
import '../common/types.dart';
import '../ex16_confirmation/confirmation.dart';
import '../ex21_i18n/translations.dart';
import '../ex23_login/command.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final storage = await SharedPreferences.getInstance();
  final translations = Translations('ex25', storage);
  await translations.start();
  runApp(
    MultiProvider(
      providers: [
        Provider.value(value: Api(CookieClient(storage))),
        ChangeNotifierProvider.value(value: translations),
      ],
      child: MaterialApp(
        debugShowCheckedModeBanner: false,
        theme: ThemeData(colorSchemeSeed: Colors.indigo),
        home: const ClientsPage(),
      ),
    ),
  );
}

// os campos do formulário
enum Field { title, firstName, lastName, login, password }

class ClientsPage extends StatefulWidget {
  const ClientsPage({super.key});

  @override
  State<ClientsPage> createState() => _ClientsPageState();
}

class _ClientsPageState extends State<ClientsPage> {
  late final Api _api = context.read<Api>();
  User? _user;
  List<Person> _clients = [];

  // o formulário: _editedId == null -> criação, caso contrário atualização
  int? _editedId;
  int _version = 0;
  String _title = 'Mr';
  final _texts = {
    for (final c in [Field.firstName, Field.lastName, Field.login, Field.password]) c: TextEditingController(),
  };
  // o erro de cada campo (uma CHAVE de tradução), devolvido pelo servidor
  Map<String, String> _errors = {};
  // a mensagem geral do último erro, e a de um sucesso (chave + parâmetros)
  ApiError? _pageError;
  ({String key, Map<String, String> params})? _success;
  // envio ao servidor: um Command (exemplo 23), que informa se está em andamento
  final _sending = Command();

  bool get _isAdmin => _user?.role == Role.admin;

  @override
  void dispose() {
    for (final c in _texts.values) {
      c.dispose();
    }
    _sending.dispose();
    super.dispose();
  }

  Future<void> _reload() async {
    final clients = Person.list(await _api.get('/clients'));
    if (mounted) setState(() => _clients = clients);
  }

  Future<void> _onUserChange(User? u) async {
    setState(() {
      _user = u;
      _clients = [];
    });
    if (u?.role == Role.admin) await _reload();
  }

  void _clearMessages() {
    _errors = {};
    _pageError = null;
    _success = null;
  }

  void _newForm() {
    setState(() {
      _editedId = null;
      _version = 0;
      _title = 'Mr';
      for (final c in _texts.values) {
        c.clear();
      }
      _clearMessages();
    });
  }

  void _edit(Person c) {
    setState(() {
      _editedId = c.id;
      // a VERSÃO lida com o registro volta com a atualização: se alguém
      // modificou o registro nesse meio tempo, o servidor responderá 409 CONCURRENT_UPDATE
      _version = c.version;
      _title = c.title;
      _texts[Field.firstName]!.text = c.firstName;
      _texts[Field.lastName]!.text = c.lastName;
      _texts[Field.login]!.text = c.login ?? '';
      _texts[Field.password]!.clear();
      _clearMessages();
    });
  }

  Future<void> _save() async {
    setState(_clearMessages);
    final input = {
      'title': _title,
      for (final MapEntry(key: field, value: c) in _texts.entries) field.name: c.text,
      'version': _version,
    };
    try {
      final client = Person.fromJson(
        _editedId == null ? await _api.post('/clients', input) : await _api.put('/clients/$_editedId', input),
      );
      final key = _editedId == null ? 'FORM.ADDED' : 'FORM.UPDATED';
      _newForm(); // formulário limpo, mensagens limpas...
      // ... exceto esta
      setState(
        () => _success = (key: key, params: {'name': '${client.firstName} ${client.lastName}', 'login': client.login ?? ''}),
      );
      await _reload();
    } on ApiError catch (e) {
      setState(() {
        _pageError = e; // a mensagem geral
        _errors = e.fields; // o erro de cada campo
      });
    }
  }

  Future<void> _delete(Person c) async {
    final t = context.read<Translations>().t;
    final name = '${c.firstName} ${c.lastName}';
    final yes = await confirm(context, t('FORM.DELETE_CONFIRM', {'name': name}));
    if (!yes || !mounted) return;
    setState(_clearMessages);
    try {
      await _api.delete('/clients/${c.id}');
      setState(() => _success = (key: 'FORM.DELETED', params: {'name': name}));
    } on ApiError catch (e) {
      setState(() => _pageError = e);
    }
    await _reload();
  }

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final t = translations.t;

    // um campo de entrada, com seu erro (uma chave do servidor) traduzido
    Widget field(Field c, {bool secret = false}) => TextField(
      controller: _texts[c],
      obscureText: secret,
      decoration: InputDecoration(
        labelText: t('FORM.${c.name.toUpperCase()}'),
        errorText: _errors[c.name] == null ? null : t(_errors[c.name]!),
        errorMaxLines: 2,
      ),
      // um campo modificado: seu erro desaparece
      onChanged: (_) {
        if (_errors.containsKey(c.name)) setState(() => _errors = {..._errors}..remove(c.name));
      },
    );

    final success = _success;
    final pageError = _pageError;
    return Scaffold(
      appBar: AppBar(
        title: Text(t('FORM.PAGE_TITLE')),
        actions: [
          // o idioma: um menu
          PopupMenuButton<String>(
            icon: const Icon(Icons.translate),
            onSelected: translations.changeLanguage,
            itemBuilder: (_) => [for (final l in languages) PopupMenuItem(value: l, child: Text(l.toUpperCase()))],
          ),
        ],
      ),
      body: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          LoginBar(onUserChange: _onUserChange),
          if (_user != null && !_isAdmin)
            Card(
              color: Colors.amber.shade50,
              child: Padding(padding: const EdgeInsets.all(12), child: Text(t('FORM.ADMIN_ONLY'))),
            ),
          if (_isAdmin) ...[
            for (final c in _clients)
              ListTile(
                dense: true,
                title: Text(c.fullName),
                subtitle: Text(c.login ?? ''),
                trailing: Row(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    IconButton(tooltip: t('FORM.EDIT'), icon: const Icon(Icons.edit), onPressed: () => _edit(c)),
                    IconButton(
                      tooltip: t('FORM.DELETE'),
                      icon: const Icon(Icons.delete_outline, color: Colors.red),
                      onPressed: () => _delete(c),
                    ),
                  ],
                ),
              ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
                      t(_editedId == null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT'),
                      style: Theme.of(context).textTheme.titleMedium,
                    ),
                    // um título "Dr" que o servidor recusará: para ver ERRORS.INVALID_TITLE
                    DropdownButton<String>(
                      value: _title,
                      items: [
                        for (final title in ['Mr', 'Mme', 'Melle', 'Dr'])
                          DropdownMenuItem(value: title, child: Text(title)),
                      ],
                      onChanged: (v) => setState(() {
                        _title = v!;
                        _errors = {..._errors}..remove('title');
                      }),
                    ),
                    if (_errors['title'] != null)
                      Text(t(_errors['title']!), style: const TextStyle(color: Colors.red, fontSize: 12)),
                    field(Field.firstName),
                    field(Field.lastName),
                    field(Field.login),
                    field(Field.password, secret: true),
                    const SizedBox(height: 12),
                    ListenableBuilder(
                      listenable: _sending,
                      builder: (context, _) => Wrap(
                        spacing: 8,
                        children: [
                          FilledButton(
                            onPressed: _sending.running ? null : () => _sending.execute(_save),
                            child: Text(t('FORM.SAVE')),
                          ),
                          OutlinedButton(onPressed: _newForm, child: Text(t('FORM.CANCEL'))),
                        ],
                      ),
                    ),
                    if (success != null)
                      Padding(
                        padding: const EdgeInsets.only(top: 12),
                        child: Text(t(success.key, success.params), style: const TextStyle(color: Colors.green)),
                      ),
                    // a mensagem geral, e o status HTTP, para entender
                    if (pageError != null)
                      Padding(
                        padding: const EdgeInsets.only(top: 12),
                        child: Text.rich(
                          TextSpan(
                            children: [
                              TextSpan(
                                text: t(pageError.key, pageError.params),
                                style: const TextStyle(color: Colors.red),
                              ),
                              TextSpan(
                                text: '  ($pageError)',
                                style: const TextStyle(color: Colors.grey, fontSize: 12),
                              ),
                            ],
                          ),
                        ),
                      ),
                  ],
                ),
              ),
            ),
          ],
        ],
      ),
    );
  }
}

Gerenciamento de pacientes (conta admin). Este formulário não faz nenhuma validação no celular: tudo é enviado ao servidor, que responde, em caso de rejeição, com um JSON de erro, convertido em [ApiError].

  • linhas 37–43: as traduções do exemplo 21, usando os dicionários desse exemplo;
  • linha 77: o erro de cada campo: uma CHAVE de tradução, devolvida pelo servidor;
  • linhas 79–82: a mensagem geral do último erro, a mensagem de sucesso e o [Command] enviado ao servidor (exemplo 23);
  • linhas 126–131: a versão lida do registro é atualizada com a alteração: se alguém tiver modificado o registro nesse meio-tempo, o servidor responderá com um 409 [CONCURRENT_UPDATE] (bloqueio otimista);
  • linhas 141–162: a operação de salvar: [POST /api/clients] (criação) ou [PUT /api/clients/:id] (atualização). Se a operação for rejeitada, [ApiError] devolve uma mensagem de erro geral e o erro específico de cada campo;
  • linhas 188–198: um campo de entrada: seu erro, uma chave do servidor, é traduzido e exibido abaixo do campo ([errorText]); editar o campo limpa o seu erro;
  • linhas 209–212: um menu na barra superior para a seleção do idioma;
  • linha 257: um título “Dr”, que o servidor rejeitará: veja [ERRORS.INVALID_TITLE];
  • linhas 291–302: a mensagem geral, traduzida e, para contexto, o status HTTP e a chave.

Um formulário vazio; um homônimo (“Alice DURAND”); o mesmo, em francês:

Experimente também: um login que já está em uso ([martin]), um login inválido (“Jean M”) e o mesmo registro editado em dois dispositivos (ou no aplicativo e com o [curl]).

O princípio é o mesmo de todos os formulários do estudo de caso: as regras residem em UM só lugar, o servidor; a aplicação exibe os resultados no idioma do usuário.