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]:
| <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. Exemplo 23: login, cookie e sessão
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.