Skip to content

9. Comunicación con el servidor

El servidor JSON [RdvMedecins] debe estar iniciado ahora (puerto 8080), como se explicó en el capítulo anterior.

9.1. Ejemplo 22: una primera solicitud HTTP

9.1.1. ¿Dónde está el servidor?

Para un cliente web servido por el propio servidor, la pregunta no se plantea: las solicitudes se envían al mismo origen que la página, con una dirección relativa ([/api/captcha]). Una aplicación móvil no tiene origen: hay que indicarle la dirección completa del servidor. Y esa dirección depende de dónde se ejecute la aplicación:

// =========================================================================
// lib/common/config.dart - ¿DÓNDE está el servidor JSON?
// -------------------------------------------------------------------------
// La pregunta no se plantea para una aplicación web servida por el propio
// servidor: las solicitudes van al MISMO origen que la página
// (una dirección relativa, /api/...). Pero una aplicación MÓVIL no tiene
// origen: hay que darle la dirección completa del servidor.
//   - el emulador de Android ve la computadora que lo ejecuta en
//     la dirección 10.0.2.2 (localhost, para él, es el propio emulador);
//   - un teléfono real, conectado a la misma red Wi-Fi que la computadora, debe
//     usar la dirección de la computadora en esta red (192.168.1.20...):
//     se indica al lanzar la aplicación:
//         flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...
//   - en el desarrollo web (flutter run -d chrome), el servidor de desarrollo de
//     Flutter reenvía las solicitudes /api al servidor JSON
//     (archivo web_dev_config.yaml): basta una dirección relativa;
//   - en una computadora (Windows, macOS, Linux): localhost.
// =========================================================================

import 'package:flutter/foundation.dart';

// el valor dado por --dart-define=SERVER=..., '' por defecto.
// String.fromEnvironment se evalúa en tiempo de COMPILACIÓN: es una constante
const _forcedServer = String.fromEnvironment('SERVER');

class Config {
  // kIsWeb: true si la aplicación se ejecuta en un navegador;
  // defaultTargetPlatform: el sistema (android, iOS, windows...)
  static String serverUrl = _forcedServer.isNotEmpty
      ? _forcedServer
      : kIsWeb
      ? '' // mismo origen: direcciones relativas
      : defaultTargetPlatform == TargetPlatform.android
      ? 'http://10.0.2.2:8080'
      : 'http://localhost:8080';
}
  • línea 24: una dirección proporcionada al iniciar la aplicación, mediante la opción [--dart-define]: [flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...]. [String.fromEnvironment] se evalúa en tiempo de compilación: es una constante, “”, si no se proporciona la opción;
  • líneas 29–35: de lo contrario, una dirección predeterminada, según la plataforma. [kIsWeb] es verdadero si la aplicación se ejecuta en un navegador; [defaultTargetPlatform] indica en qué sistema se ejecuta ([TargetPlatform.android], [TargetPlatform.windows]...):
    • en la web: una dirección relativa (''), el mismo origen que la aplicación;
    • en el emulador [Android]: [http://10.0.2.2:8080]. El emulador es una máquina independiente con su propia red: para el emulador, [localhost] se refiere al propio emulador. La dirección especial [10.0.2.2] se refiere a la computadora que lo ejecuta;
    • en una computadora ([Windows]...): [http://localhost:8080].

Un teléfono real, conectado a la misma red Wi-Fi que la computadora del servidor, debe usar la dirección de la computadora en esa red (el comando [ipconfig] de [Windows] la proporciona): se pasa mediante [--dart-define]. El firewall de la computadora también debe permitir las conexiones entrantes en el puerto 8080.

Se requieren dos ajustes en el proyecto [Android], en el archivo [android/app/src/main/AndroidManifest.xml]:

1
2
3
4
5
6
7
8
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- acceso a la red (el 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">
  • línea 3: permiso para usar la red. Durante el desarrollo, [Flutter] lo agrega automáticamente (para la recarga en caliente); debe declararse explícitamente para la aplicación publicada;
  • Línea 8: a partir de la versión 9 de [Android], una aplicación solo puede comunicarse mediante HTTPS. Nuestro servidor de desarrollo usa HTTP (“sin cifrar”): lo permitimos. En producción, el servidor usaría HTTPS y se eliminaría esta línea.

Y para la web: el servidor de desarrollo de [Flutter] ([flutter run -d chrome]) sirve la aplicación en su propio puerto; el servidor JSON, en cambio, está en el puerto 8080. Son dos orígenes distintos: el navegador se negaría a incluir la cookie en las solicitudes e incluso a leerla en las respuestas (el servidor no permite solicitudes de un origen diferente, es decir, “CORS”). El archivo [web_dev_config.yaml] configura el servidor de desarrollo web de [Flutter] (desde la versión 3.38):

# ==========================================================================
# web_dev_config.yaml - el servidor de desarrollo WEB de Flutter
# --------------------------------------------------------------------------
# flutter run -d chrome sirve la aplicación en http://localhost:5173 y
# reenvía toda solicitud /api/... al servidor JSON de RdvMedecins (puerto 8080):
# para el navegador, la aplicación y la API tienen el MISMO origen (sin
# CORS, y la cookie del token viaja). Ejemplos 22 a 25.
# ==========================================================================

server:
  host: localhost
  port: 5173
  proxy:
    - target: "http://localhost:8080/"
      prefix: "/api/"
  • línea 12: la aplicación web se sirve en el puerto 5173;
  • líneas 13–15: un proxy: toda solicitud a una dirección que comience con [/api/] se reenvía al servidor JSON (puerto 8080) y su respuesta se devuelve al navegador. Para el navegador, la aplicación y la API tienen el mismo origen. Es exactamente el papel del proxy de [Vite] en el curso de [React].

9.1.2. La solicitud

// =========================================================================
// lib/ex22_http/main.dart - una primera solicitud HTTP al servidor
// -------------------------------------------------------------------------
// El servidor JSON de RdvMedecins debe estar iniciado (puerto 8080). Le pedimos
// un CAPTCHA: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - http.get(uri): la función del paquete http que envía una
//     solicitud GET. Devuelve un Future de la respuesta (http.Response): su código
//     de estado (statusCode), sus encabezados (headers), su cuerpo (body);
//   - jsonDecode(text): el cuerpo JSON -> objetos Dart (Map, List...);
//   - la dirección del servidor depende de dónde se ejecute la aplicación
//     (emulador de Android, teléfono, navegador...): ver common/config.dart;
//   - tres estados que mostrar: en curso, exitoso, fallido;
//   - la imagen del CAPTCHA es SVG: el paquete flutter_svg puede dibujarla.
// =========================================================================

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> {
  // lo que devuelve GET /api/captcha: un record
  ({String id, String svg})? _captcha;
  bool _loading = true;
  String? _error;
  int _requestCount = 0;
  int _requestNumber = 0; // el número de la última solicitud

  @override
  void initState() {
    super.initState();
    _load(); // la primera solicitud, en cuanto aparece la pantalla
  }

  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 NO lanza una excepción ante una respuesta de error (4xx,
      // 5xx): se comprueba el código de estado
      if (response.statusCode != 200) {
        throw Exception('the server answered ${response.statusCode} ${response.reasonPhrase}');
      }
      final json = jsonDecode(response.body) as Map<String, dynamic>;
      // la respuesta de una solicitud OBSOLETA (entretanto se hizo una nueva), o
      // una que llegó después de cerrar la pantalla: se ignora
      if (!mounted || number != _requestNumber) return;
      setState(() {
        _captcha = (id: json['id'] as String, svg: json['svg'] as String);
        _requestCount++;
        _loading = false;
      });
    } catch (e) {
      // ninguna respuesta (servidor detenido, dirección incorrecta...), o un error
      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: dibujar una imagen 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)),
        ],
      ),
    );
  }
}
  • línea 21: el paquete [http], el cliente HTTP del equipo de [Dart]. [as http]: sus funciones se usan con un prefijo ([http.get], [http.Response]), lo que evita que sus nombres se confundan con otros;
  • líneas 44–48: el estado: el CAPTCHA recibido (un registro, o [null]), los tres estados de una solicitud (en curso, error, exitosa) y el número de solicitudes exitosas;
  • líneas 51–53: la primera solicitud se envía en cuanto aparece la pantalla;
  • líneas 56–84: la solicitud:
    • línea 63: [http.get] envía una solicitud GET y más tarde devuelve un [Future<http.Response>]: la respuesta. [Uri.parse] construye la dirección a partir de una cadena;
    • líneas 66–67: [http.get] NO lanza una excepción ante una respuesta de error (4xx, 5xx): es una respuesta más. Verificamos su código de estado;
    • línea 69: [response.body] es el cuerpo de la respuesta, el texto; [jsonDecode] lo convierte en objetos [Dart]: en este caso, un [Map];
    • línea 72: la respuesta a una solicitud OBSOLETA (mientras tanto se pidió otra imagen), o una que llega después de que la pantalla se cerró, se ignora (véase el ejemplo 19);
    • línea 74: JSON es de tipo [dynamic]: cada valor se convierte a su tipo correspondiente, mediante [as];
    • líneas 78–82: ninguna respuesta (servidor caído, dirección incorrecta, red desconectada): [http.get] lanza una excepción, que se captura y se muestra;
  • línea 102: una barra de progreso durante la solicitud;
  • línea 122: la imagen del CAPTCHA es un SVG, en forma de texto: [SvgPicture.string] (paquete [flutter_svg]) la renderiza. La genera NUESTRO servidor y no contiene nada proporcionado por un usuario;
  • línea 130: “Otra imagen”, deshabilitado durante una solicitud.

En el emulador de [Android]; luego, con el servidor JSON apagado:

La herramienta [Flutter DevTools] (iniciada desde [VS Code], o mediante la dirección que muestra [flutter run]) tiene una pestaña Network que muestra cada solicitud HTTP de la aplicación, con sus encabezados y su cuerpo, de forma similar a las herramientas de desarrollo de un navegador.

9.2.1. Un cliente HTTP que gestiona cookies

El servidor guarda el token JWT en una cookie. En un navegador, este se encarga de guardar y enviar las cookies; el código de la aplicación no necesita hacer nada. En un teléfono NO hay navegador: le corresponde a la aplicación encargarse de ello.

// =========================================================================
// lib/common/http_client.dart - un cliente HTTP que gestiona las COOKIES
// -------------------------------------------------------------------------
// El servidor de RdvMedecins coloca el token JWT en una COOKIE (httpOnly).
// En un navegador, es el navegador quien guarda las cookies y las reenvía
// con cada solicitud: el código de la aplicación no tiene nada que hacer.
// En un teléfono NO hay navegador: le corresponde a la aplicación
// cumplir su función, es decir:
//   1. leer el encabezado "Set-Cookie" de cada respuesta y guardar las cookies;
//   2. reenviarlas en el encabezado "Cookie" de cada solicitud.
// Este cliente HTTP lo hace, ENVOLVIENDO el cliente del paquete http
// (http.BaseClient: basta con escribir el método send). Las cookies se
// guardan también en el dispositivo (shared_preferences): seguimos con la sesión
// iniciada al detener y reiniciar la aplicación.
// En la web, no hace más que el cliente ordinario: el
// navegador prohíbe a la aplicación leer o escribir estos encabezados.
// =========================================================================

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;
  // nombre de la cookie -> su valor
  final Map<String, String> _cookies = {};

  CookieClient([this._storage]) {
    // las cookies guardadas durante un 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
  // (varias cookies se separan con comas). Solo conservamos el
  // nombre y el valor de cada cookie; un valor vacío (cierre de sesión) la elimina
  void _store(String setCookie) {
    // un nombre seguido de "=", al comienzo del encabezado o después de una coma
    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();
}
  • Línea 25: el paquete [http] permite envolver su cliente: se hereda de [http.BaseClient] y basta con implementar el método [send], por el que pasan todas las solicitudes ([get], [post]...);
  • líneas 28–31: el cliente envuelto, el almacenamiento del dispositivo (opcional: [?]) y las cookies (nombre → valor);
  • líneas 33–37: al crearse, las cookies guardadas durante un uso anterior de la aplicación. Esto mantiene la sesión iniciada al cerrar y volver a abrir la aplicación: en un teléfono, equivale a que un navegador conserve sus cookies de una visita a otra;
  • líneas 42–52: cada solicitud recibe el encabezado [Cookie] (“rdvmedecins_jwt=eyJhbGci...; other=value”) y luego se lee el encabezado [Set-Cookie] de la respuesta. [kIsWeb]: en la web, la aplicación no hace más que un cliente normal, porque el navegador le impide leer o escribir estos encabezados (los gestiona él mismo);
  • líneas 58–69: el encabezado [Set-Cookie]. Varias cookies se separan con comas, pero la propia fecha [Expires] contiene una coma (“Tue, 29 Sep 2026”): la expresión regular solo reconoce un nombre seguido de [=], ya sea al comienzo del encabezado o después de una coma. De cada cookie solo se conservan el nombre y el valor; un valor vacío (cierre de sesión: el servidor envía [rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970...]) elimina la cookie. [_storage?.setString(...)]: la llamada se realiza solo si [_storage] no es [null].

Existe una gestión de cookies más completa (dominios, rutas, fechas de vencimiento) en paquetes ([cookie_jar], con el cliente [dio]); nuestra implementación, de solo unas pocas líneas, basta para UN servidor. Nota de seguridad: aquí el token se guarda en texto plano en el dispositivo. Una aplicación de producción usaría el paquete [flutter_secure_storage] (véase el ejemplo 20).

9.2.2. Un comando

// =========================================================================
// lib/ex23_login/command.dart - una ACCIÓN, su estado, su resultado
// -------------------------------------------------------------------------
// Una acción asíncrona (iniciar sesión, guardar...) tiene un estado que
// la pantalla debe mostrar: ¿está EN CURSO (botón deshabilitado, indicador)? ¿terminó
// con un ERROR (mensaje)? Es el patrón "Command" de la guía de
// arquitectura de Flutter, reducido a lo esencial:
//
//     final login = Command();
//     login.execute(() => logIn(...));          // lanza la acción
//     login.running, login.error               // su estado
//
// Un Command es un ChangeNotifier: la pantalla lo escucha (ListenableBuilder)
// y se redibuja cuando comienza y cuando termina.
// =========================================================================

import 'package:flutter/foundation.dart';

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

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

  // ejecuta la acción, si no hay otra en curso
  Future<void> execute(Future<void> Function() action) async {
    if (_running) return; // sin doble envío (doble toque en el botón)
    _running = true;
    _error = null;
    notifyListeners();
    try {
      await action();
    } catch (e) {
      _error = e; // el error se CONSERVA, para mostrarlo
    } finally {
      // finally: se ejecuta en TODOS los casos, éxito o error
      _running = false;
      notifyListeners();
    }
  }

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

Una acción asíncrona (iniciar sesión, guardar, etc.) tiene un estado que la pantalla debe mostrar: ¿está en curso (botón deshabilitado)? ¿Terminó con un error (mensaje)? Este es el modelo “Command” de la guía de arquitectura de [Flutter], reducido a lo esencial. El curso de [React] usaba para esto las “acciones” de [React] 19 ([useActionState]).

  • Líneas 27–39: ejecutar una acción: si hay otra acción en curso, no se hace nada (para evitar un doble envío si se pulsa dos veces el botón); de lo contrario, el comando pasa a “en curso” y notifica a sus oyentes; si ocurre una excepción, el error se registra para mostrarlo; en todos los casos ([finally]), el comando deja de estar en curso.

9.2.3. La pantalla

// =========================================================================
// lib/ex23_login/main.dart - inicio de sesión en el servidor RdvMedecins
// -------------------------------------------------------------------------
//   1. al iniciar: GET /api/auth/me - ¿ya hay una sesión iniciada?
//      (la aplicación pudo haberse detenido; el servidor, por su parte, lee la cookie
//      que se le presenta);
//   2. inicio de sesión: POST /api/auth/login, cuerpo JSON { login, password,
//      captchaId, captcha }. Si tiene éxito, el servidor envía la cookie
//      del token JWT (encabezado Set-Cookie);
//   3. solicitud protegida: GET /api/doctors. La cookie viaja con ella;
//   4. cierre de sesión: POST /api/auth/logout - el servidor borra la cookie.
// En el teléfono, es CookieClient (common/http_client.dart) quien
// almacena la cookie y la reenvía; en la web, es el 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';

// los pocos mensajes que necesita este ejemplo (el ejemplo 25 usará diccionarios)
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),
    ),
  );
}

// una respuesta que no es 2xx se convierte en una excepción, que conserva la respuesta
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: nadie ha iniciado sesión
  List<dynamic> _doctors = [];
  Map<String, dynamic>? _captcha;
  bool _ready = false; // ¿terminó la verificación inicial?
  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');

  // una solicitud GET de la que queremos el cuerpo JSON; una excepción si no es 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));
  }

  // un POST con un cuerpo JSON
  Future<http.Response> _post(String path, Object body) {
    return widget.client.post(
      _url(path),
      headers: {'content-type': 'application/json'}, // el cuerpo es 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. ¿quién ha iniciado sesión? 200 -> el usuario; 401 -> nadie
  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 SOLO este tipo de excepción
      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. el inicio de sesión: una acción ejecutada por el Command, que almacena su error
  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) {
      // el cuerpo JSON de la respuesta de error: { statusCode, key, ... }
      final error = jsonDecode(response.body) as Map<String, dynamic>;
      final key = error['key'] as String;
      await _loadCaptcha(); // cada imagen se usa una sola vez
      throw '${response.statusCode} - ${messages[key] ?? key}'; // se puede lanzar... una cadena
    }
    _password.clear();
    setState(() => _user = jsonDecode(response.body) as Map<String, dynamic>);
    await _loadDoctors();
  }

  // 4. el cierre de sesión
  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) {
      // sesión iniciada
      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) {
      // sin sesión iniciada: el formulario
      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: esta parte sigue el estado del comando
              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(); // un widget "vacío"
    }

    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!)),
            ),
        ],
      ),
    );
  }
}
  • líneas 36–41: el cliente HTTP, que guarda sus cookies en el dispositivo, se crea al inicio y se pasa a la pantalla;
  • líneas 47–49: una excepción que captura la respuesta como un error (allí se puede leer su código de estado). [implements Exception]: un objeto que se puede lanzar ([throw]);
  • líneas 90–93: una solicitud (GET) de la que se quiere el cuerpo (JSON), y una excepción si el código de estado no es 2xx. [widget.client.get(...)]: el cliente con cookies. [utf8.decode(response.bodyBytes)]: el cuerpo decodificado en UTF-8 (los acentos), sin importar lo que indique el encabezado de la respuesta;
  • líneas 97–101: un POST: el encabezado es [content-type: application/json] y el cuerpo está en JSON (el servidor rechaza un POST que no sea JSON);
  • Líneas 117–132: 1. Al inicio: ¿quién tiene la sesión iniciada? [GET /api/auth/me]: 200, el usuario; 401, nadie. [on ErrorResponse catch (e)] captura SOLO este tipo de excepción; la siguiente, [catch], todas las demás (ninguna respuesta);
  • líneas 136–152: 2. inicio de sesión: [POST /api/auth/login]. Si se rechaza la solicitud, el cuerpo de la respuesta de error proporciona la clave del mensaje; se carga una nueva imagen (cada una se usa una sola vez) y luego se lanza el mensaje: en [Dart], se puede lanzar cualquier objeto, en este caso, una cadena. Es el comando quien la captura y la guarda;
  • líneas 156–162: 4. Cierre de sesión: [POST /api/auth/logout]; el servidor elimina la cookie (y el cliente también elimina sus cookies);
  • líneas 193–197: 3. sesión iniciada: la lista de médicos ([GET /api/doctors], una solicitud protegida: la cookie la acompaña);
  • líneas 225–226: el CAPTCHA y su botón;
  • líneas 236–248: el botón refleja el estado de la solicitud: deshabilitado y con “Iniciando sesión...” mientras se envía la solicitud; cualquier mensaje de error aparece debajo.

La pantalla de inicio de sesión; una contraseña incorrecta; inicio de sesión exitoso:

Cierre y reinicie la aplicación: arrancará con la sesión iniciada. La cookie, guardada en el dispositivo, se presenta a [GET /api/auth/me] y el servidor responde con las credenciales del usuario. El token vence después de dos horas: [GET /api/auth/me] devolverá entonces una respuesta 401 y volverá a aparecer la pantalla de inicio de sesión.

9.3. Ejemplo 24: una capa de acceso a la API

En el ejemplo 23, cada solicitud repetía los mismos pasos. Este ejemplo los organiza en tres capas, que el caso de estudio retomará.

9.3.1. Los tipos

// =========================================================================
// lib/common/types.dart - los objetos JSON intercambiados con la API de RdvMedecins
// (vea el capítulo sobre la caja negra, que describe cada ruta)
// -------------------------------------------------------------------------
// El JSON decodificado no está tipado: Map<String, dynamic>, List...
// Cada clase tiene un constructor "factory" fromJson que VERIFICA la forma
// del JSON recibido, con el "pattern matching" de Dart 3:
//
//   switch (json) {
//     {'login': String login, 'name': String name} => ...   // la forma esperada
//     _ => throw FormatException(...)                       // todo lo demás
//   }
//
// El patrón {'login': String login, ...} verifica que json es un Map, que
// esas claves existen, que sus valores tienen el tipo correcto, y almacena
// esos valores en variables. Una respuesta inesperada se detecta
// de inmediato, y no más tarde, en pleno despliegue en pantalla.
// =========================================================================

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'),
  };
}

// un médico o un 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; // solo para el 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,
    } =>
      // la clave "login" es opcional: se lee por separado
      Person(id, version, title, firstName, lastName, (json as Map<String, Object?>)['login'] as String?),
    _ => throw FormatException('unexpected Person: $json'),
  };

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

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

// el nombre de una persona, y nada más
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';
}

// una línea 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'),
  };
}

El JSON decodificado no tiene tipos: [Map], [List], [dynamic]. Cada clase tiene un constructor factory [fromJson] que valida el formato del JSON recibido. Un constructor [factory] no necesariamente crea un objeto nuevo: es una función que devuelve un objeto de la clase.

  • Líneas 33–39: [Dart] 3, coincidencia de patrones aplicada a JSON. El patrón [{'login': final String login, 'name': final String name, 'role': final String role}] verifica que [json] es un [Map], que existen estas tres claves, que sus valores son cadenas, y guarda esos valores en tres variables. Si el JSON tiene un formato distinto, como ocurre con [_], se trata como una excepción. Así, una respuesta inesperada se detecta en cuanto se recibe, en lugar de más tarde, en medio de la visualización;
  • línea 23: “ADMIN” -> [Role.admin]: [byName] obtiene un valor de una enumeración a partir de su nombre;
  • líneas 67–76: el patrón verifica las claves obligatorias; la clave opcional [login] se lee por separado;
  • línea 81: un JSON de lista -> una lista de personas;
  • líneas 133–144: [final Object? patient] acepta cualquier valor, incluido [null]; [final int? appointmentId], un entero, o [null];
  • líneas 162–164: un getter de formato.

9.3.2. Errores

// =========================================================================
// lib/common/api_error.dart - UNA sola clase para todos los errores de la API
// -------------------------------------------------------------------------
// Todas las respuestas de error del servidor RdvMedecins tienen la misma forma:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Pero una solicitud también puede fallar de OTRA manera: sin ninguna respuesta
// (red caída, servidor detenido, dirección incorrecta), o con una respuesta que no
// viene de nuestro servidor (una página de error de un proxy). Convertimos
// todo esto en UNA sola clase, ApiError, que lleva la clave de traducción
// enviada por el servidor (y, si los hay, sus parámetros y el error de
// cada campo).
// =========================================================================

import 'dart:convert';

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

// "implements Exception": un objeto que se puede lanzar (throw) y capturar (catch)
class ApiError implements Exception {
  final int statusCode; // 0: el servidor no respondió
  final String key; // p. ej. '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 {}});

  // una respuesta de error (4xx, 5xx) -> un ApiError
  factory ApiError.fromResponse(http.Response response) {
    Object? body;
    try {
      body = jsonDecode(utf8.decode(response.bodyBytes));
    } on FormatException {
      body = null; // no es JSON: no respondió nuestro servidor
    }
    // el "pattern matching" de un Map: si el cuerpo tiene una clave
    // "key" de tipo String, se almacena en la variable 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']));
    }
    // sin clave: respondió el proxy o la red en su lugar
    return ApiError(
      response.statusCode,
      response.statusCode >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }

  // un objeto JSON { "name": "ERRORS..." } -> Map<String, String> (vacío en caso contrario)
  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 las respuestas de error del servidor tienen el mismo formato. Sin embargo, una solicitud también puede fallar DE OTRA FORMA: ninguna respuesta, o una respuesta que no proviene de nuestro servidor. Convertimos todo esto en UNA sola clase, [ApiError].

  • Líneas 19–23: un estado (0: ninguna respuesta), una clave de traducción, sus parámetros y el error de cada campo;
  • líneas 28–44: una respuesta de error → un [ApiError]. [if (body case {'key': final String key})]: filtrado en un [if] (“if-case”): si el cuerpo tiene una clave [key] de tipo cadena, se guarda en la variable [key]. De lo contrario, no fue nuestro servidor quien respondió;
  • línea 53: “401 LOGIN.ERROR”, para una visualización rápida.

9.3.3. Las solicitudes

// =========================================================================
// lib/common/api.dart - solicitudes a la API, en una línea
// -------------------------------------------------------------------------
// En el ejemplo 23, cada solicitud repetía los mismos pasos: dirección del
// servidor, prefijo /api, encabezado JSON, prueba del código de estado, lectura del
// cuerpo del error... Aquí se reúnen:
//
//   final json = await api.get('/doctors');
//   await api.post('/appointments', {'day': day, 'slotId': 3});
//
//   - si tiene éxito, el Future devuelve el cuerpo JSON, DECODIFICADO (Maps,
//     Lists, Strings, números...);
//   - si falla, se completa con un ApiError.
// Todas las solicitudes pasan por el método request: es el lugar donde
// se trataría un problema COMÚN a todas (vea el caso de estudio y la
// respuesta 401). Lo usan los ejemplos 24 y 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) {
      // un cuerpo JSON (el servidor rechaza un POST que no lo tenga)
      request.headers['content-type'] = 'application/json';
      request.body = jsonEncode(body);
    }
    final http.Response response;
    try {
      // send envía la solicitud; fromStream espera el cuerpo completo de la respuesta
      response = await http.Response.fromStream(await _client.send(request));
    } catch (_) {
      // SIN respuesta (red, servidor detenido, dirección incorrecta)
      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);
  // un POST siempre tiene un cuerpo JSON: {} por defecto
  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);
}
  • Líneas 31–49: TODAS las solicitudes pasan por este método: la dirección del servidor y el prefijo [/api], el cuerpo en JSON, el envío ([_client.send], seguido de [http.Response.fromStream], que espera el cuerpo completo), los errores convertidos en [ApiError] y el cuerpo de la respuesta decodificado. Aquí es donde se manejaría un problema común a todas las solicitudes (véase el caso de estudio y la respuesta 401);
  • líneas 52–56: cuatro atajos. Un POST siempre tiene un cuerpo JSON: [{}] de forma predeterminada.

9.3.4. Una barra de inicio de sesión

// =========================================================================
// lib/common/login_bar.dart - inicio / cierre de sesión, en una sola barra
// -------------------------------------------------------------------------
// El formulario del ejemplo 23, reducido a una barra y reescrito con api.dart.
// El widget llama a onUserChange con el usuario que inició sesión (o
// null) cada vez que cambia, incluido al iniciar, después de
// consultar GET /api/auth/me. El objeto Api se lee en el contexto
// (provisto por provider, vea el main de los ejemplos 24 y 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: se lee en el contexto, en 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);
  }

  // al iniciar: ¿ya hay una sesión iniciada?
  Future<void> _start() async {
    try {
      _setUser(User.fromJson(await _api.get('/auth/me')));
    } on ApiError {
      _setUser(null); // 401: nadie ha iniciado sesión
      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: [
                      // la imagen SVG del captcha, producida por NUESTRO servidor (vea el ejemplo 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)),
                ],
              ),
      ),
    );
  }
}

El formulario del ejemplo 23, reducido a una sola barra y reescrito con [Api]. Llama a [onUserChange] cada vez que cambia el usuario con sesión iniciada, incluso al inicio.

  • Línea 30: el objeto [Api] se proporciona más arriba (mediante [provider]); [late]: se lee solo en su primer uso, en [initState];
  • Líneas 64–72: al inicio, ¿quién tiene la sesión iniciada? [User.fromJson(await _api.get('/auth/me'))]: una sola línea. Cualquier [ApiError] significa “nadie”;
  • líneas 77–92: la conexión, en pocas líneas: los errores aparecen como [ApiError].

9.3.5. La capa de acceso a la API

// =========================================================================
// lib/ex24_api_layer/rdvmedecins.dart - la capa de acceso a la API
// -------------------------------------------------------------------------
// Un método tipado por cada ruta de la API. Las pantallas no conocen ni las
// URL, ni el paquete http, ni el formato JSON: llaman a métodos
// que devuelven objetos Dart (Person, Schedule...).
// Es el equivalente en el cliente de la capa DAO del lado del servidor: si la API
// cambia (una URL, un nombre de campo), solo se modifica este archivo.
// En la guía de arquitectura de Flutter, es un "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 construye "doctorId=1&day=2030-01-15", codificando lo necesario
  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]: un parámetro opcional. '?clientId' en el Map: la clave
  // solo se coloca en el Map si clientId no es 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');
}

Un método por ruta de la API, tipado. Las pantallas desconocen las direcciones, el paquete [http] y el formato JSON: llaman a métodos que devuelven objetos [Dart]. Si la API cambia (una dirección, el nombre de un campo), solo se modifica este archivo. La guía de arquitectura de [Flutter] llama a esta capa “repositorio”.

  • Línea 26: [Uri] construye la cadena “doctorId=1&day=2030-01-15”, codificando los datos necesarios;
  • línea 33: ['clientId': ?clientId] dentro de un literal [Map]: la clave se coloca en el [Map] solo si [clientId] no es [null] (los “elementos opcionales” de [Dart] 3.8).

9.3.6. El modelo de vista

// =========================================================================
// lib/ex24_api_layer/schedule_model.dart - el "view model" de la pantalla
// -------------------------------------------------------------------------
// La guía de arquitectura de Flutter recomienda separar:
//   - la VISTA: los widgets, que muestran y transmiten las acciones del
//     usuario;
//   - el VIEW MODEL (ViewModel): un ChangeNotifier que contiene el estado
//     de la pantalla (el médico elegido, el día, la agenda recibida...), las
//     acciones (elegir, reservar, cancelar), y que llama a la capa de acceso
//     a la API.
// La vista ya no tiene lógica: es sencilla de leer; el view model
// no tiene widgets: es sencillo de probar.
//
// También hace lo que no queremos reescribir en cada pantalla:
//   - un CACHÉ: la agenda de cada (médico, día) ya leída se conserva; al
//     volver a ella se muestra de inmediato, mientras se vuelve a leer en segundo plano;
//   - las respuestas OBSOLETAS se ignoran (vea el ejemplo 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);

  // ==== el estado ====
  User? user;
  List<Person> doctors = [];
  List<Person> clients = [];
  int? doctorId;
  String day = formatDay(DateTime.now().add(const Duration(days: 1))); // mañana
  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;

  // ==== las acciones ====
  Future<void> changeUser(User? u) async {
    user = u;
    doctors = [];
    clients = [];
    schedule = null;
    doctorId = null;
    _cache.clear(); // los derechos cambiaron: se olvida todo
    notifyListeners();
    if (u == null) return;
    doctors = await _rdvmedecins.getDoctors();
    if (isManager) clients = await _rdvmedecins.getClients(); // un USER recibiría 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.');

  // una acción, y luego SIEMPRE una nueva lectura de la agenda: el SERVIDOR es la referencia
  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;
    // primero el caché (o nada), luego la lectura
    schedule = _cache[key];
    loading = true;
    notifyListeners();
    try {
      final fetched = await _rdvmedecins.getSchedule(id, day);
      if (number != _readNumber) return; // se lanzó una lectura más reciente
      schedule = _cache[key] = fetched;
    } on ApiError catch (e) {
      if (number != _readNumber) return;
      schedule = null;
      message = (success: false, text: '$e');
    }
    loading = false;
    notifyListeners();
  }
}

La guía de arquitectura de [Flutter] recomienda separar la vista (los widgets, que muestran y transmiten las acciones del usuario) y el modelo de vista (un [ChangeNotifier] que contiene el estado de la pantalla y sus acciones, y que llama a la capa de acceso a la API). La vista ya no contiene ninguna lógica; el modelo de vista no tiene widgets: se puede probar sin una pantalla.

  • líneas 35–43: el estado de la pantalla;
  • líneas 45–46: una caché: se guarda la agenda de cada par (médico, día) que ya se leyó; al volver a él se muestra de inmediato mientras se vuelve a leer. Y el número de la última lectura, para ignorar las respuestas obsoletas (véase el ejemplo 19). Esto, en pocas líneas, es lo que hace la biblioteca [TanStack Query] del curso de [React];
  • líneas 49–50: valores calculados;
  • líneas 53–64: un nuevo usuario: se borra todo (los permisos cambiaron), luego se leen los médicos y, para ADMIN y DOCTOR, los clientes (un USER recibiría un 403);
  • líneas 91–98: una acción (reservar, cancelar) y luego SIEMPRE una nueva lectura de la agenda: la respuesta del servidor tiene prioridad;
  • líneas 101–120: obtención de la agenda: primero desde la caché (o nada), luego la respuesta del servidor, a menos que mientras tanto se haya iniciado una obtención más reciente.

9.3.7. La pantalla

// =========================================================================
// lib/ex24_api_layer/main.dart - una agenda, con la capa de acceso a la API
// -------------------------------------------------------------------------
// Inicie sesión (barra superior), elija un médico y un día:
// se muestra la agenda. ADMIN y DOCTOR pueden reservar para un paciente y
// cancelar; un paciente (martin...) reserva para sí mismo. Cada acción
// termina con una nueva lectura de la agenda.
// Tres capas, de abajo hacia arriba:
//   Api (common/api.dart)          las solicitudes HTTP, los errores;
//   RdvMedecins (rdvmedecins.dart) un método tipado por cada ruta de la API;
//   ScheduleModel (schedule_model.dart) el estado y las acciones de la pantalla;
// y la vista, a continuación, que solo muestra el modelo.
// =========================================================================

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: provee un objeto ordinario (que no 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: la clave enviada por el servidor cuando un paciente ya tiene una cita próxima
              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),
            ],
          ],
        ],
      ),
    );
  }
}

// una fila de la agenda: el rango horario, el ocupante, los botones 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),
      // los botones siguen los derechos calculados por el 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,
    );
  }
}
  • líneas 28–34: las tres capas, ensambladas al inicio: [Api] (las solicitudes), [RdvMedecins] (las rutas), [ScheduleModel] (la pantalla). [Provider.value] proporciona un objeto normal, que no dispara ninguna notificación;
  • línea 50: la vista se suscribe al modelo de vista;
  • línea 58: la barra de inicio de sesión notifica al modelo;
  • el resto es solo visualización: cada widget lee el estado del modelo y, cuando el usuario actúa, llama a uno de sus métodos ([model.chooseDoctor(id!)], [model.book(c)]...);
  • líneas 120–153: una fila de la agenda. Los botones siguen los permisos calculados por el servidor ([bookable], [appointmentId]).

Con sesión iniciada como [admin], la agenda de la Sra. PELISSIER; se reserva un horario para un paciente; con sesión iniciada como [martin] (rol USER), la misma agenda:

El paciente [martin] no puede ver el nombre del paciente del horario reservado: el servidor no se lo envió.

9.4. Ejemplo 25: errores devueltos por el servidor

9.4.1. Los diccionarios

{
  "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."
  }
}

Los mensajes de error del servidor son claves (“ERRORS.LASTNAME_REQUIRED”): el diccionario las traduce.

9.4.2. La pantalla

// =========================================================================
// lib/ex25_server_errors/main.dart - mostrar los errores del SERVIDOR
// -------------------------------------------------------------------------
// La gestión de los clientes (cuenta admin). Este formulario no realiza,
// DELIBERADAMENTE, ninguna validación en el teléfono: todo se envía al
// servidor, que responde, en caso de rechazo, con un error JSON (convertido en un
// 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' }         (bloqueo optimista)
//
// El error de CADA campo (ApiError.fields) se almacena en el estado y
// se muestra debajo del campo (errorText); su mensaje es la CLAVE enviada por
// el servidor, que la pantalla traduce (diccionarios del ejemplo 21).
// Modificar un campo borra su error.
// Pruebe: un apellido vacío, un título "Dr", un homónimo (Alice DURAND), un
// login ya tomado (martin), el mismo registro modificado en dos 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(),
      ),
    ),
  );
}

// los campos del formulario
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 = [];

  // el formulario: _editedId == null -> creación, de lo contrario actualización
  int? _editedId;
  int _version = 0;
  String _title = 'Mr';
  final _texts = {
    for (final c in [Field.firstName, Field.lastName, Field.login, Field.password]) c: TextEditingController(),
  };
  // el error de cada campo (una CLAVE de traducción), devuelto por el servidor
  Map<String, String> _errors = {};
  // el mensaje general del último error, y el de un éxito (clave + parámetros)
  ApiError? _pageError;
  ({String key, Map<String, String> params})? _success;
  // envío al servidor: un Command (ejemplo 23), que indica si está en curso
  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;
      // la VERSIÓN leída con el registro vuelve con la actualización: si alguien
      // modificó el registro mientras tanto, el 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(); // formulario vaciado, mensajes borrados...
      // ... excepto este
      setState(
        () => _success = (key: key, params: {'name': '${client.firstName} ${client.lastName}', 'login': client.login ?? ''}),
      );
      await _reload();
    } on ApiError catch (e) {
      setState(() {
        _pageError = e; // el mensaje general
        _errors = e.fields; // el error 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;

    // un campo de entrada, con su error (una clave del servidor) traducido
    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,
      ),
      // un campo modificado: su error 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: [
          // el idioma: un menú
          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,
                    ),
                    // un título "Dr" que el servidor rechazará: 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)),
                      ),
                    // el mensaje general, y el estado 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),
                              ),
                            ],
                          ),
                        ),
                      ),
                  ],
                ),
              ),
            ),
          ],
        ],
      ),
    );
  }
}

Gestión de pacientes (cuenta de administrador). Este formulario no realiza ninguna validación en el teléfono: todo se envía al servidor, que responde, en caso de rechazo, con un JSON de error, convertido en [ApiError].

  • Líneas 37–43: las traducciones del ejemplo 21, con los diccionarios de ese ejemplo;
  • línea 77: el error de cada campo: una CLAVE de traducción, devuelta por el servidor;
  • líneas 79–82: el mensaje general del último error, el mensaje de éxito y el [Command] enviado al servidor (ejemplo 23);
  • líneas 126–131: la versión leída del registro se actualiza con el cambio: si alguien modificó el registro mientras tanto, el servidor responderá con un 409 [CONCURRENT_UPDATE] (bloqueo optimista);
  • líneas 141–162: la operación de guardado: [POST /api/clients] (creación) o [PUT /api/clients/:id] (actualización). Si se rechaza la operación, [ApiError] devuelve un mensaje de error general y el error específico de cada campo;
  • líneas 188–198: un campo de entrada: su error, una clave del servidor, se traduce y se muestra debajo del campo ([errorText]); al editar el campo se borra su error;
  • líneas 209–212: un menú en la barra superior para seleccionar el idioma;
  • línea 257: un título “Dr”, que el servidor rechazará: véase [ERRORS.INVALID_TITLE];
  • líneas 291–302: el mensaje general, traducido y, a modo de contexto, el estado HTTP y la clave.

Un formulario vacío; un homónimo (“Alice DURAND”); lo mismo, en francés:

Pruebe también: un nombre de usuario que ya está en uso ([martin]), un nombre de usuario no válido (“Jean M”) y el mismo registro editado en dos dispositivos (o en la aplicación y con [curl]).

El principio es el mismo que en todos los formularios del caso de estudio: las reglas residen en UN solo lugar, el servidor; la aplicación muestra los resultados en el idioma del usuario.