Skip to content

9. Kommunikation mit dem Server

Der JSON-[RdvMedecins]-Server muss nun gestartet sein (Port 8080), wie im vorherigen Kapitel erklärt.

9.1. Beispiel 22: Eine erste HTTP-Anfrage

9.1.1. Wo befindet sich der Server?

Für einen Web-Client, der vom Server selbst ausgeliefert wird, stellt sich die Frage nicht: Anfragen werden mit einer relativen Adresse an denselben Ursprung wie die Seite gesendet ([/api/captcha]). Eine mobile App hat keinen Ursprung: Man muss ihr die vollständige Adresse des Servers mitteilen. Und diese Adresse hängt davon ab, wo die App läuft:

// =========================================================================
// lib/common/config.dart - WO liegt der JSON-Server?
// -------------------------------------------------------------------------
// Die Frage stellt sich nicht für eine Web-Anwendung, die vom Server selbst ausgeliefert wird: Die
// Anfragen gehen an denselben Ursprung wie die Seite
// (eine relative Adresse, /api/...). Eine MOBILE Anwendung hat aber keinen
// Ursprung: Ihr muss die vollständige Adresse des Servers angegeben werden.
//   - Der Android-Emulator sieht den Computer, auf dem er läuft, unter
//     der Adresse 10.0.2.2 (localhost ist für ihn der Emulator selbst);
//   - ein echtes Telefon, das mit demselben WLAN wie der Computer verbunden ist, muss
//     die Adresse des Computers in diesem Netzwerk verwenden (192.168.1.20 ...):
//     Sie wird beim Start der Anwendung angegeben:
//         flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...
//   - bei der Web-Entwicklung (flutter run -d chrome) leitet der Entwicklungsserver
//     von Flutter die /api-Anfragen an den JSON-Server weiter
//     (Datei web_dev_config.yaml): Eine relative Adresse genügt;
//   - auf einem Computer (Windows, macOS, Linux): localhost.
// =========================================================================

import 'package:flutter/foundation.dart';

// der von --dart-define=SERVER=... angegebene Wert, standardmäßig ''.
// String.fromEnvironment wird zur KOMPILIERZEIT ausgewertet: Es ist eine Konstante
const _forcedServer = String.fromEnvironment('SERVER');

class Config {
  // kIsWeb: true, wenn die Anwendung in einem Browser läuft;
  // defaultTargetPlatform: das System (android, iOS, windows ...)
  static String serverUrl = _forcedServer.isNotEmpty
      ? _forcedServer
      : kIsWeb
      ? '' // gleicher Ursprung: relative Adressen
      : defaultTargetPlatform == TargetPlatform.android
      ? 'http://10.0.2.2:8080'
      : 'http://localhost:8080';
}
  • Zeile 24: eine Adresse, die beim Start der App über die Option [--dart-define] übergeben wird: [flutter run --dart-define=SERVER=http://192.168.1.20:8080 ...]. [String.fromEnvironment] wird zur Kompilierzeit ausgewertet: Es ist eine Konstante, „“, wenn die Option nicht angegeben wird;
  • Zeilen 29–35: andernfalls eine Standardadresse, je nach Plattform. [kIsWeb] ist true, wenn die Anwendung in einem Browser läuft; [defaultTargetPlatform] gibt an, auf welchem System sie läuft ([TargetPlatform.android], [TargetPlatform.windows]...):
    • im Web: eine relative Adresse (''), derselbe Ursprung wie die Anwendung;
    • auf dem Emulator [Android]: [http://10.0.2.2:8080]. Der Emulator ist ein eigenständiger Rechner mit eigenem Netzwerk: Aus seiner Sicht bezeichnet [localhost] den Emulator selbst. Die Spezialadresse [10.0.2.2] bezeichnet den Computer, auf dem er läuft;
    • auf einem Computer ([Windows] ...): [http://localhost:8080].

Ein echtes Smartphone, das mit demselben WLAN wie der Server-Computer verbunden ist, muss die Adresse des Computers in diesem Netzwerk verwenden (der Befehl [ipconfig] unter [Windows] liefert sie): Sie wird über [--dart-define] übergeben. Die Firewall des Computers muss außerdem eingehende Verbindungen auf Port 8080 zulassen.

Zwei Einstellungen im [Android]-Projekt sind erforderlich, und zwar in der Datei [android/app/src/main/AndroidManifest.xml]:

1
2
3
4
5
6
7
8
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Netzwerkzugriff (der JSON-Server) -->
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:label="examples_flutter"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        android:usesCleartextTraffic="true">
  • Zeile 3: die Berechtigung zur Nutzung des Netzwerks. Während der Entwicklung fügt [Flutter] sie automatisch hinzu (für Hot Reload); für die ausgelieferte Anwendung muss sie ausdrücklich deklariert werden;
  • Zeile 8: Ab Version 9 von [Android] darf eine Anwendung nur noch über HTTPS kommunizieren. Unser Entwicklungsserver verwendet HTTP („unverschlüsselt“): Wir erlauben das. In der Produktion würde der Server HTTPS verwenden, und diese Zeile würde entfernt.

Und für das Web: Der Entwicklungsserver von [Flutter] ([flutter run -d chrome]) liefert die Anwendung auf einem eigenen Port aus; der JSON-Server dagegen liegt auf Port 8080. Das sind zwei verschiedene Ursprünge: Der Browser würde sich weigern, den Cookie in die Anfragen aufzunehmen und ihn sogar in den Antworten zu lesen (der Server erlaubt keine Anfragen von einem anderen Ursprung, nämlich „CORS“). Die Datei [web_dev_config.yaml] konfiguriert den [Flutter]-Webentwicklungsserver (seit Version 3.38):

# ==========================================================================
# web_dev_config.yaml - der WEB-Entwicklungsserver von Flutter
# --------------------------------------------------------------------------
# flutter run -d chrome liefert die Anwendung unter http://localhost:5173 aus und
# leitet jede Anfrage /api/... an den JSON-Server von RdvMedecins weiter (Port 8080):
# Für den Browser haben die Anwendung und die API denselben Ursprung (kein
# CORS, und das Token-Cookie wird mitgesendet). Beispiele 22 bis 25.
# ==========================================================================

server:
  host: localhost
  port: 5173
  proxy:
    - target: "http://localhost:8080/"
      prefix: "/api/"
  • Zeile 12: Die Webanwendung wird auf Port 5173 ausgeliefert;
  • Zeilen 13–15: ein Proxy: Jede Anfrage an eine Adresse, die mit [/api/] beginnt, wird an den JSON-Server (Port 8080) weitergeleitet, und seine Antwort wird an den Browser zurückgegeben. Für den Browser haben Anwendung und API denselben Ursprung. Genau das ist die Rolle des [Vite]-Proxys im Kurs [React].

9.1.2. Die Anfrage

// =========================================================================
// lib/ex22_http/main.dart - eine erste HTTP-Anfrage an den Server
// -------------------------------------------------------------------------
// Der JSON-Server von RdvMedecins muss gestartet sein (Port 8080). Wir fragen ihn nach
// einem CAPTCHA: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - http.get(uri): die Funktion des Pakets http, die eine
//     GET-Anfrage sendet. Sie gibt ein Future der Antwort zurück (http.Response): ihren Statuscode
//     (statusCode), ihre Header (headers), ihren Body (body);
//   - jsonDecode(text): der JSON-Body -> Dart-Objekte (Map, List ...);
//   - die Adresse des Servers hängt davon ab, wo die Anwendung läuft
//     (Android-Emulator, Telefon, Browser ...): siehe common/config.dart;
//   - drei Zustände sind anzuzeigen: in Bearbeitung, erfolgreich, fehlgeschlagen;
//   - das Bild des CAPTCHA ist ein SVG: Das Paket flutter_svg kann es zeichnen.
// =========================================================================

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> {
  // was GET /api/captcha zurückgibt: ein Record
  ({String id, String svg})? _captcha;
  bool _loading = true;
  String? _error;
  int _requestCount = 0;
  int _requestNumber = 0; // die Nummer der letzten Anfrage

  @override
  void initState() {
    super.initState();
    _load(); // die erste Anfrage, sobald der Bildschirm erscheint
  }

  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 löst bei einer Fehlerantwort (4xx,
      // 5xx) KEINE Exception aus: Der Statuscode wird geprüft
      if (response.statusCode != 200) {
        throw Exception('the server answered ${response.statusCode} ${response.reasonPhrase}');
      }
      final json = jsonDecode(response.body) as Map<String, dynamic>;
      // die Antwort auf eine ÜBERHOLTE Anfrage (inzwischen wurde eine neue gestellt) oder
      // eine, die nach dem Schließen des Bildschirms ankam: Sie wird ignoriert
      if (!mounted || number != _requestNumber) return;
      setState(() {
        _captcha = (id: json['id'] as String, svg: json['svg'] as String);
        _requestCount++;
        _loading = false;
      });
    } catch (e) {
      // überhaupt keine Antwort (Server gestoppt, falsche Adresse ...) oder ein Fehler
      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: ein als Text gegebenes SVG-Bild zeichnen
            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)),
        ],
      ),
    );
  }
}
  • Zeile 21: das Paket [http], der HTTP-Client des [Dart]-Teams. [as http]: Seine Funktionen werden mit einem Präfix verwendet ([http.get], [http.Response]), das verhindert, dass ihre Namen mit anderen verwechselt werden;
  • Zeilen 44–48: der Zustand: das empfangene CAPTCHA (ein Record oder [null]), die drei Zustände einer Anfrage (läuft, Fehler, erfolgreich), die Anzahl der erfolgreichen Anfragen;
  • Zeilen 51–53: Die erste Anfrage wird gesendet, sobald der Bildschirm erscheint;
  • Zeilen 56–84: die Anfrage:
    • Zeile 63: [http.get] sendet eine GET-Anfrage und liefert später ein [Future<http.Response>]: die Antwort. [Uri.parse] erstellt die Adresse aus einem String;
    • Zeilen 66–67: [http.get] löst bei einer Fehlerantwort (4xx, 5xx) KEINE Exception aus: Sie ist einfach eine weitere Antwort. Wir prüfen ihren Statuscode;
    • Zeile 69: [response.body] ist der Body der Antwort, der Text; [jsonDecode] wandelt ihn in [Dart]-Objekte um: hier in eine [Map];
    • Zeile 72: Die Antwort auf eine ÜBERHOLTE Anfrage (ein Bild wurde in der Zwischenzeit erneut angefordert) oder eine Antwort, die nach dem Schließen des Bildschirms eintrifft, wird ignoriert (siehe Beispiel 19);
    • Zeile 74: JSON ist vom Typ [dynamic]: Jeder Wert wird mit [as] in den passenden Typ umgewandelt;
    • Zeilen 78–82: überhaupt keine Antwort (Server nicht erreichbar, falsche Adresse, Netzwerk getrennt): [http.get] wirft eine Exception, die abgefangen und angezeigt wird;
  • Zeile 102: ein Fortschrittsbalken während der Anfrage;
  • Zeile 122: Das CAPTCHA-Bild liegt als SVG in Textform vor: [SvgPicture.string] (Paket [flutter_svg]) stellt es dar. Es wird von UNSEREM Server erzeugt und enthält nichts, was von einem Benutzer stammt;
  • Zeile 130: „Anderes Bild“, während einer Anfrage deaktiviert.

Auf dem [Android]-Emulator; dann bei heruntergefahrenem JSON-Server:

Das Werkzeug [Flutter DevTools] (gestartet über [VS Code] oder über die Adresse, die [flutter run] angibt) hat einen Tab „Network“, der jede HTTP-Anfrage der Anwendung mit ihren Headern und ihrem Body anzeigt, ähnlich den Entwicklertools eines Browsers.

9.2.1. Ein HTTP-Client, der Cookies verwaltet

Der Server speichert das JWT-Token in einem Cookie. In einem Browser übernimmt der Browser das Speichern und Senden von Cookies; der Code der Anwendung muss nichts tun. Auf einem Smartphone gibt es KEINEN Browser – die Anwendung muss sich selbst darum kümmern.

// =========================================================================
// lib/common/http_client.dart - ein HTTP-Client, der COOKIES verwaltet
// -------------------------------------------------------------------------
// Der RdvMedecins-Server legt das JWT-Token in einem COOKIE ab (httpOnly).
// In einem Browser speichert der Browser die Cookies und sendet sie
// bei jeder Anfrage zurück: Der Code der Anwendung muss nichts tun.
// Auf einem Telefon gibt es KEINEN Browser: Es ist Sache der Anwendung,
// seine Rolle zu übernehmen, das heißt:
//   1. den Header "Set-Cookie" jeder Antwort lesen und die Cookies speichern;
//   2. sie im Header "Cookie" jeder Anfrage zurücksenden.
// Dieser HTTP-Client erledigt das, indem er den Client des Pakets http UMHÜLLT
// (http.BaseClient: Es genügt, die Methode send zu schreiben). Die Cookies werden
// außerdem auf dem Gerät gespeichert (shared_preferences): Wir bleiben angemeldet,
// wenn wir die Anwendung beenden und neu starten.
// Im Web tut er nicht mehr als der gewöhnliche Client: Der
// Browser verbietet der Anwendung, diese Header zu lesen oder zu schreiben.
// =========================================================================

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;
  // Cookie-Name -> sein Wert
  final Map<String, String> _cookies = {};

  CookieClient([this._storage]) {
    // die bei einer früheren Nutzung gespeicherten Cookies
    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
  // (mehrere Cookies werden durch Kommas getrennt). Wir behalten nur den
  // Namen und den Wert jedes Cookies; ein leerer Wert (Logout) löscht es
  void _store(String setCookie) {
    // ein Name, gefolgt von "=", am Anfang des Headers oder nach einem Komma
    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();
}
  • Zeile 25: Das Paket [http] erlaubt es, Ihren Client zu umhüllen : Sie erben von [http.BaseClient] und müssen nur die Methode [send] implementieren, über die alle Anfragen laufen ([get], [post]...);
  • Zeilen 28–31: der umhüllte Client, der Speicher des Geräts (optional: [?]) und die Cookies (Name → Wert);
  • Zeilen 33–37: bei der Erstellung die Cookies, die bei einer früheren Nutzung der App gespeichert wurden. Dadurch bleiben Sie angemeldet, wenn Sie die App schließen und erneut öffnen: Auf einem Smartphone entspricht das einem Browser, der seine Cookies von einem Besuch zum nächsten behält;
  • Zeilen 42–52: Jede Anfrage erhält den Header [Cookie] („rdvmedecins_jwt=eyJhbGci...; other=value“), anschließend wird der Header [Set-Cookie] der Antwort gelesen. [kIsWeb]: Im Web tut die App nicht mehr als ein gewöhnlicher Client, da der Browser die App daran hindert, diese Header zu lesen oder zu schreiben (er verwaltet sie selbst);
  • Zeilen 58–69: der Header [Set-Cookie]. Mehrere Cookies werden durch Kommas getrennt, aber das Datum [Expires] enthält selbst ein Komma („Tue, 29 Sep 2026“): Der reguläre Ausdruck erfasst nur einen Namen, auf den [=] folgt, entweder am Anfang des Headers oder nach einem Komma. Von jedem Cookie werden nur Name und Wert behalten; ein leerer Wert (Abmeldung: Der Server sendet [rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970...]) löscht den Cookie. [_storage?.setString(...)]: Der Aufruf erfolgt nur, wenn [_storage] nicht [null] ist.

Eine umfassendere Cookie-Verwaltung (Domains, Pfade, Ablaufdaten) bieten Pakete ([cookie_jar], mit dem Client [dio]); unsere Implementierung aus nur wenigen Zeilen genügt für EINEN Server. Sicherheitshinweis: Das Token wird hier im Klartext auf dem Gerät gespeichert. Eine Produktionsanwendung würde das Paket [flutter_secure_storage] verwenden (siehe Beispiel 20).

9.2.2. Ein Command

// =========================================================================
// lib/ex23_login/command.dart - eine AKTION, ihr Zustand, ihr Ergebnis
// -------------------------------------------------------------------------
// Eine asynchrone Aktion (Anmelden, Speichern ...) hat einen Zustand, den
// der Bildschirm anzeigen muss: Läuft sie GERADE (Schaltfläche deaktiviert, Indikator)?
// Endete sie mit einem FEHLER (Meldung)? Es ist das "Command"-Muster
// des Architekturleitfadens von Flutter, auf das Wesentliche reduziert:
//
//     final login = Command();
//     login.execute(() => logIn(...));          // startet die Aktion
//     login.running, login.error               // ihr Zustand
//
// Ein Command ist ein ChangeNotifier: Der Bildschirm hört ihn ab (ListenableBuilder)
// und zeichnet sich beim Start und beim Ende neu.
// =========================================================================

import 'package:flutter/foundation.dart';

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

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

  // führt die Aktion aus, sofern nicht bereits eine andere läuft
  Future<void> execute(Future<void> Function() action) async {
    if (_running) return; // kein doppeltes Senden (Doppeltippen auf den Button)
    _running = true;
    _error = null;
    notifyListeners();
    try {
      await action();
    } catch (e) {
      _error = e; // der Fehler wird BEHALTEN, um ihn anzuzeigen
    } finally {
      // finally: wird in JEDEM Fall ausgeführt, bei Erfolg oder Fehler
      _running = false;
      notifyListeners();
    }
  }

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

Eine asynchrone Aktion (Anmelden, Speichern usw.) hat einen Zustand, den der Bildschirm anzeigen muss: Ist sie in Bearbeitung (Schaltfläche deaktiviert)? Endete sie mit einem Fehler (Meldung)? Das ist das „Command“-Modell aus dem Architekturleitfaden von [Flutter], auf das Wesentliche reduziert. Im Kurs [React] dienten dafür die „Actions“ von [React] 19 ([useActionState]).

  • Zeilen 27–39: eine Aktion ausführen: Läuft bereits eine andere Aktion, geschieht nichts (um doppeltes Senden zu verhindern, wenn die Schaltfläche zweimal gedrückt wird); andernfalls wechselt das Command in den Zustand „in Bearbeitung“ und benachrichtigt seine Listener; bei einer Exception wird der Fehler gespeichert , damit er angezeigt wird; in allen Fällen ([finally]) ist das Command danach nicht mehr in Bearbeitung.

9.2.3. Der Bildschirm

// =========================================================================
// lib/ex23_login/main.dart - Anmeldung am RdvMedecins-Server
// -------------------------------------------------------------------------
//   1. beim Start: GET /api/auth/me - sind wir bereits angemeldet?
//      (Die Anwendung kann beendet worden sein; der Server liest seinerseits das Cookie,
//      das ihm präsentiert wird);
//   2. Login: POST /api/auth/login, JSON-Body { login, password,
//      captchaId, captcha }. Bei Erfolg sendet der Server das Cookie
//      des JWT-Tokens (Set-Cookie-Header);
//   3. geschützte Anfrage: GET /api/doctors. Das Cookie wird mitgeschickt;
//   4. Logout: POST /api/auth/logout - der Server löscht das Cookie.
// Auf dem Smartphone speichert und sendet CookieClient (common/http_client.dart)
// das Cookie zurück; im Web übernimmt das der Browser.
// =========================================================================

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';

// die wenigen Meldungen, die dieses Beispiel braucht (Beispiel 25 verwendet Wörterbücher)
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),
    ),
  );
}

// eine Antwort, die kein 2xx ist, wird zu einer Exception, die die Antwort behält
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: niemand ist angemeldet
  List<dynamic> _doctors = [];
  Map<String, dynamic>? _captcha;
  bool _ready = false; // ist die Erstprüfung abgeschlossen?
  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');

  // eine GET-Anfrage, deren JSON-Body wir wollen; eine Exception, wenn es kein 2xx ist
  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));
  }

  // ein POST mit JSON-Body
  Future<http.Response> _post(String path, Object body) {
    return widget.client.post(
      _url(path),
      headers: {'content-type': 'application/json'}, // der Body ist 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. Wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
  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": fängt NUR diesen Exception-Typ ab
      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. das Login: eine vom Command ausgeführte Aktion, die ihren Fehler speichert
  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) {
      // der JSON-Body der Fehlerantwort: { statusCode, key, ... }
      final error = jsonDecode(response.body) as Map<String, dynamic>;
      final key = error['key'] as String;
      await _loadCaptcha(); // jedes Bild wird nur einmal verwendet
      throw '${response.statusCode} - ${messages[key] ?? key}'; // man kann... einen String werfen
    }
    _password.clear();
    setState(() => _user = jsonDecode(response.body) as Map<String, dynamic>);
    await _loadDoctors();
  }

  // 4. das 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) {
      // angemeldet
      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) {
      // nicht angemeldet: das Formular
      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: dieses Stück folgt dem Zustand des Commands
              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(); // ein "leeres" Widget
    }

    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!)),
            ),
        ],
      ),
    );
  }
}
  • Zeilen 36–41: Der HTTP-Client, der seine Cookies auf dem Gerät speichert, wird beim Start erstellt und an den Bildschirm übergeben;
  • Zeilen 47–49: eine Exception, die die Antwort als Fehler erfasst (ihr Statuscode kann dort gelesen werden). [implements Exception]: ein Objekt, das geworfen werden kann ([throw]);
  • Zeilen 90–93: eine Anfrage (GET), von der wir den Body (JSON) wollen, und eine Exception, wenn der Statuscode kein 2xx ist. [widget.client.get(...)]: der Client mit Cookies. [utf8.decode(response.bodyBytes)]: der Body, nach UTF-8 dekodiert (die Akzente), unabhängig davon, was der Antwort-Header angibt;
  • Zeilen 97–101: ein POST: Der Header ist [content-type: application/json] und der Body liegt in JSON vor (der Server weist ein POST ab, das nicht JSON ist);
  • Zeilen 117–132: 1. Beim Start: Wer ist angemeldet? [GET /api/auth/me]: 200, der Benutzer; 401, niemand. [on ErrorResponse catch (e)] fängt NUR diesen Typ von Exception ab; das folgende [catch] alle anderen (überhaupt keine Antwort);
  • Zeilen 136–152: 2. Anmeldung: [POST /api/auth/login]. Wird die Anfrage abgelehnt, liefert der Body der Fehlerantwort den Schlüssel der Meldung; ein neues Bild wird geladen (jedes wird nur einmal verwendet), dann wird die Meldung geworfen: In [Dart] kann jedes Objekt geworfen werden – hier ein String. Das Command fängt ihn ab und speichert ihn;
  • Zeilen 156–162: 4. Abmeldung: [POST /api/auth/logout]; der Server löscht den Cookie (und der Client löscht ebenfalls seine Cookies);
  • Zeilen 193–197: 3. Angemeldet: die Liste der Ärzte ([GET /api/doctors], eine geschützte Anfrage: Der Cookie begleitet sie);
  • Zeilen 225–226: das CAPTCHA und seine Schaltfläche;
  • Zeilen 236–248: Die Schaltfläche spiegelt den Zustand der Anfrage wider: deaktiviert und „Anmeldung läuft ...“, solange die Anfrage gesendet wird; eine eventuelle Fehlermeldung erscheint darunter.

Der Anmeldebildschirm; ein falsches Passwort; erfolgreiche Anmeldung:

Schließen Sie die Anwendung und starten Sie sie neu: Sie startet angemeldet. Der auf dem Gerät gespeicherte Cookie wird an [GET /api/auth/me] übergeben, und der Server antwortet mit den Daten des Benutzers. Das Token läuft nach zwei Stunden ab: [GET /api/auth/me] liefert dann eine 401-Antwort, und der Anmeldebildschirm erscheint wieder.

9.3. Beispiel 24: Eine Zugriffsschicht für die API

In Beispiel 23 wiederholte jede Anfrage dieselben Schritte. Dieses Beispiel ordnet sie in drei Schichten, auf die die Fallstudie zurückkommt.

9.3.1. Die Typen

// =========================================================================
// lib/common/types.dart - die mit der RdvMedecins-API ausgetauschten JSON-Objekte
// (siehe das Kapitel zur Blackbox, das jede Route beschreibt)
// -------------------------------------------------------------------------
// Das dekodierte JSON ist nicht typisiert: Map<String, dynamic>, List...
// Jede Klasse hat einen "factory"-Konstruktor fromJson, der die Form
// des empfangenen JSON PRÜFT, mit dem "Pattern Matching" von Dart 3:
//
//   switch (json) {
//     {'login': String login, 'name': String name} => ...   // die erwartete Form
//     _ => throw FormatException(...)                       // alles andere
//   }
//
// Das Pattern {'login': String login, ...} prüft, dass json eine Map ist, dass
// diese Schlüssel existieren, dass ihre Werte den richtigen Typ haben, und speichert
// diese Werte in Variablen. Eine unerwartete Antwort wird
// sofort erkannt und nicht erst später mitten in der Anzeige.
// =========================================================================

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

// ein Arzt oder ein Client (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; // nur für den 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,
    } =>
      // der Schlüssel "login" ist optional: er wird separat gelesen
      Person(id, version, title, firstName, lastName, (json as Map<String, Object?>)['login'] as String?),
    _ => throw FormatException('unexpected Person: $json'),
  };

  // eine JSON-Liste -> eine Liste von Personen
  static List<Person> list(Object? json) => [for (final p in json as List<Object?>) Person.fromJson(p)];

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

// der Name einer Person und sonst nichts
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';
}

// eine Zeile von 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'),
  };
}

Das dekodierte JSON ist untypisiert: [Map], [List], [dynamic]. Jede Klasse hat einen Factory-Konstruktor namens [fromJson], der das Format des empfangenen JSON validiert. Ein [factory]-Konstruktor erzeugt nicht unbedingt ein neues Objekt: Er ist eine Funktion, die ein Objekt der Klasse zurückgibt.

  • Zeilen 33–39: [Dart] 3: Pattern Matching, angewendet auf JSON. Das Muster [{'login': final String login, 'name': final String name, 'role': final String role}] prüft, dass [json] eine [Map] ist, dass diese drei Schlüssel existieren, dass ihre Werte Strings sind, und speichert diese Werte in drei Variablen. Hat das JSON ein anderes Format, wie es bei [_] der Fall ist, wird es als Exception behandelt. Eine unerwartete Antwort wird so erkannt, sobald sie eintrifft, und nicht erst später mitten in der Anzeige;
  • Zeile 23: „ADMIN“ -> [Role.admin]: [byName] liefert einen Enum-Wert anhand seines Namens;
  • Zeilen 67–76: Das Muster prüft die erforderlichen Schlüssel; der optionale Schlüssel [login] wird separat gelesen;
  • Zeile 81: eine JSON-Liste -> eine Liste von Personen;
  • Zeilen 133–144: [final Object? patient] akzeptiert jeden Wert, auch [null]; [final int? appointmentId], eine ganze Zahl oder [null];
  • Zeilen 162–164: ein Getter für die Formatierung.

9.3.2. Fehler

// =========================================================================
// lib/common/api_error.dart - EINE Klasse für alle Fehler der API
// -------------------------------------------------------------------------
// Alle Fehlerantworten des RdvMedecins-Servers haben dieselbe Form:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Eine Anfrage kann aber auch ANDERS scheitern: gar keine Antwort
// (Netzwerk ausgefallen, Server gestoppt, falsche Adresse) oder eine Antwort, die
// nicht von unserem Server kommt (eine Fehlerseite eines Proxys). Wir wandeln
// all das in EINE Klasse um, ApiError, die den vom Server gesendeten
// Übersetzungsschlüssel trägt (und, falls vorhanden, dessen Parameter sowie den Fehler
// jedes Felds).
// =========================================================================

import 'dart:convert';

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

// "implements Exception": ein Objekt, das geworfen (throw) und gefangen (catch) werden kann
class ApiError implements Exception {
  final int statusCode; // 0: der Server hat nicht geantwortet
  final String key; // z. B. '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 {}});

  // eine Fehlerantwort (4xx, 5xx) -> ein ApiError
  factory ApiError.fromResponse(http.Response response) {
    Object? body;
    try {
      body = jsonDecode(utf8.decode(response.bodyBytes));
    } on FormatException {
      body = null; // kein JSON: Es hat nicht unser Server geantwortet
    }
    // das "Pattern Matching" einer Map: Hat der Body einen Schlüssel
    // "key" vom Typ String, wird er in der Variablen key gespeichert
    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']));
    }
    // kein Schlüssel: Der Proxy oder das Netzwerk hat an seiner Stelle geantwortet
    return ApiError(
      response.statusCode,
      response.statusCode >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }

  // ein JSON-Objekt { "name": "ERRORS..." } -> Map<String, String> (sonst leer)
  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';
}

Alle Fehlerantworten des Servers haben dasselbe Format. Eine Anfrage kann jedoch auch AUF ANDERE WEISE scheitern: keine Antwort überhaupt oder eine Antwort, die nicht von unserem Server stammt. Wir wandeln all das in EINE Klasse um, [ApiError].

  • Zeilen 19–23: ein Status (0: keine Antwort), ein Übersetzungsschlüssel, seine Parameter und der Fehler zu jedem Feld;
  • Zeilen 28–44: eine Fehlerantwort → ein [ApiError]. [if (body case {'key': final String key})]: Filtern in einem [if] („If-Case“): Hat der Body einen Schlüssel [key] vom Typ String, wird er in der Variablen [key] gespeichert. Andernfalls hat nicht unser Server geantwortet;
  • Zeile 53: „401 LOGIN.ERROR“ für die schnelle Anzeige.

9.3.3. Die Anfragen

// =========================================================================
// lib/common/api.dart - Anfragen an die API in einer Zeile
// -------------------------------------------------------------------------
// In Beispiel 23 wiederholte jede Anfrage dieselben Schritte: Adresse des
// Servers, Präfix /api, JSON-Header, Test des Statuscodes, Lesen des
// Fehler-Bodys... Sie sind hier gebündelt:
//
//   final json = await api.get('/doctors');
//   await api.post('/appointments', {'day': day, 'slotId': 3});
//
//   - bei Erfolg liefert das Future den DEKODIERTEN JSON-Body (Maps,
//     Listen, Strings, Zahlen...);
//   - bei einem Fehler wird es mit einem ApiError abgeschlossen.
// Alle Anfragen laufen über die Methode request: Hier würde ein
// allen gemeinsames Problem behandelt (siehe die Fallstudie und die
// Antwort 401). Verwendet von den Beispielen 24 und 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) {
      // ein JSON-Body (der Server lehnt einen POST ohne einen solchen ab)
      request.headers['content-type'] = 'application/json';
      request.body = jsonEncode(body);
    }
    final http.Response response;
    try {
      // send sendet die Anfrage; fromStream wartet auf den vollständigen Body der Antwort
      response = await http.Response.fromStream(await _client.send(request));
    } catch (_) {
      // KEINE Antwort (Netzwerk, Server gestoppt, falsche Adresse)
      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);
  // ein POST hat immer einen JSON-Body: standardmäßig {}
  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);
}
  • Zeilen 31–49: ALLE Anfragen laufen über diese Methode: die Serveradresse und das Präfix [/api], der Body in JSON, das Senden ([_client.send], gefolgt von [http.Response.fromStream], das auf den vollständigen Body wartet), in [ApiError] umgewandelte Fehler und der dekodierte Antwort-Body. Hier würden wir ein Problem behandeln, das allen Anfragen gemeinsam ist (siehe Fallstudie und die 401-Antwort);
  • Zeilen 52–56: vier Abkürzungen. Ein POST hat immer einen JSON-Body: [{}] als Standardwert.

9.3.4. Eine Anmeldeleiste

// =========================================================================
// lib/common/login_bar.dart - An- und Abmelden in einer Leiste
// -------------------------------------------------------------------------
// Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit api.dart neu geschrieben.
// Das Widget ruft onUserChange mit dem angemeldeten Benutzer (oder
// null) bei jeder Änderung auf - auch beim Start, nach der
// Abfrage von GET /api/auth/me. Das Api-Objekt wird im Kontext gelesen
// (bereitgestellt von provider, siehe die main der Beispiele 24 und 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: wird im Kontext gelesen, in 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);
  }

  // beim Start: sind wir bereits angemeldet?
  Future<void> _start() async {
    try {
      _setUser(User.fromJson(await _api.get('/auth/me')));
    } on ApiError {
      _setUser(null); // 401: niemand ist angemeldet
      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: [
                      // das SVG-Bild des Captchas, von UNSEREM Server erzeugt (siehe Beispiel 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)),
                ],
              ),
      ),
    );
  }
}

Das Formular aus Beispiel 23, auf eine einzige Leiste reduziert und mit [Api] neu geschrieben. Sie ruft [onUserChange] bei jeder Änderung des angemeldeten Benutzers auf, auch beim Start.

  • Zeile 30: Das Objekt [Api] wird weiter oben bereitgestellt (von [provider]); [late]: Es wird erst bei der ersten Verwendung gelesen, in [initState];
  • Zeilen 64–72: Beim Start, wer ist angemeldet? [User.fromJson(await _api.get('/auth/me'))]: eine Zeile. Jeder [ApiError] bedeutet „niemand“;
  • Zeilen 77–92: die Anmeldung in wenigen Zeilen: Fehler erscheinen als [ApiError].

9.3.5. Die Zugriffsschicht für die API

// =========================================================================
// lib/ex24_api_layer/rdvmedecins.dart - die API-Zugriffsschicht
// -------------------------------------------------------------------------
// Eine typisierte Methode pro Route der API. Die Bildschirme kennen weder die
// URLs noch das Paket http noch das JSON-Format: Sie rufen Methoden auf,
// die Dart-Objekte zurückgeben (Person, Schedule...).
// Das ist das clientseitige Gegenstück zur DAO-Schicht auf der Serverseite: Ändert sich
// die API (eine URL, ein Feldname), wird nur diese Datei geändert.
// Im Architektur-Leitfaden von Flutter ist das ein "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 baut "doctorId=1&day=2030-01-15" und kodiert dabei, was nötig ist
  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]: ein optionaler Parameter. '?clientId' in der Map: Der Schlüssel
  // wird nur dann in die Map eingefügt, wenn clientId nicht null ist (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');
}

Eine typisierte Methode pro Route der API. Die Bildschirme kennen weder die Adressen noch das Paket [http] noch das JSON-Format: Sie rufen Methoden auf, die [Dart]-Objekte zurückgeben. Ändert sich die API (eine Adresse, ein Feldname), wird nur diese Datei angepasst. Der Architekturleitfaden von [Flutter] bezeichnet diese Schicht als „Repository“.

  • Zeile 26: [Uri] erstellt den String „doctorId=1&day=2030-01-15“ und kodiert dabei die nötigen Daten;
  • Zeile 33: ['clientId': ?clientId] in einem [Map]-Literal: Der Schlüssel wird nur dann in die [Map] eingefügt, wenn [clientId] nicht [null] ist (die „optionalen Elemente“ von [Dart] 3.8).

9.3.6. Das ViewModel

// =========================================================================
// lib/ex24_api_layer/schedule_model.dart - das "View Model" des Bildschirms
// -------------------------------------------------------------------------
// Der Architektur-Leitfaden von Flutter empfiehlt, zu trennen:
//   - die VIEW: die Widgets, die anzeigen und die Aktionen des
//     Benutzers weitergeben;
//   - das VIEW MODEL (ViewModel): ein ChangeNotifier, der den Zustand
//     des Bildschirms hält (der gewählte Arzt, der Tag, der empfangene Terminkalender...), die
//     Aktionen (wählen, buchen, stornieren) und der die API-Zugriffsschicht
//     aufruft.
// Die View enthält keine Logik mehr: Sie ist einfach zu lesen; das View Model
// enthält keine Widgets: Es ist einfach zu testen.
//
// Es übernimmt auch, was wir nicht für jeden Bildschirm neu schreiben wollen:
//   - einen CACHE: Der Terminkalender jedes bereits gelesenen (Arzt, Tag) wird behalten;
//     kehrt man dorthin zurück, wird er sofort angezeigt, während er im Hintergrund erneut gelesen wird;
//   - die VERALTETEN Antworten werden ignoriert (siehe Beispiel 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);

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

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

  // ---- berechnete Werte ----
  bool get loggedIn => user != null;
  bool get isManager => loggedIn && user!.role != Role.user;

  // ---- die Aktionen ----
  Future<void> changeUser(User? u) async {
    user = u;
    doctors = [];
    clients = [];
    schedule = null;
    doctorId = null;
    _cache.clear(); // die Rechte haben sich geändert: alles wird vergessen
    notifyListeners();
    if (u == null) return;
    doctors = await _rdvmedecins.getDoctors();
    if (isManager) clients = await _rdvmedecins.getClients(); // ein USER würde 403 erhalten
    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.');

  // eine Aktion, dann IMMER ein erneutes Lesen des Terminkalenders: Der SERVER ist die Referenz
  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;
    // zuerst der Cache (oder nichts), dann das Lesen
    schedule = _cache[key];
    loading = true;
    notifyListeners();
    try {
      final fetched = await _rdvmedecins.getSchedule(id, day);
      if (number != _readNumber) return; // ein neueres Lesen wurde gestartet
      schedule = _cache[key] = fetched;
    } on ApiError catch (e) {
      if (number != _readNumber) return;
      schedule = null;
      message = (success: false, text: '$e');
    }
    loading = false;
    notifyListeners();
  }
}

Der Architekturleitfaden von [Flutter] empfiehlt, die View (die Widgets, die Benutzeraktionen anzeigen und weiterleiten) und das ViewModel (ein [ChangeNotifier] , der den Zustand des Bildschirms und seine Aktionen enthält und die Zugriffsschicht für die API aufruft) zu trennen. Die View enthält keine Logik mehr; das ViewModel hat keine Widgets: Es kann ohne Bildschirm getestet werden.

  • Zeilen 35–43: der Zustand des Bildschirms;
  • Zeilen 45–46: ein Cache: Der Terminkalender jedes bereits gelesenen Paares (Arzt, Tag) wird gespeichert; kehrt man dorthin zurück, wird er sofort angezeigt, während er neu gelesen wird. Dazu kommt die Nummer des zuletzt gelesenen Eintrags, um überholte Antworten zu ignorieren (siehe Beispiel 19). Das ist, in wenigen Zeilen, das, was die Bibliothek [TanStack Query] aus dem Kurs [React] leistet;
  • Zeilen 49–50: berechnete Werte;
  • Zeilen 53–64: ein neuer Benutzer: Wir leeren alles (die Berechtigungen haben sich geändert), lesen dann die Ärzte und, für ADMIN und DOCTOR, die Klienten (ein USER erhielte eine 403);
  • Zeilen 91–98: eine Aktion (buchen, stornieren), danach IMMER ein erneutes Lesen des Terminkalenders: Die Antwort des Servers hat Vorrang;
  • Zeilen 101–120: das Abrufen des Terminkalenders: zuerst aus dem Cache (oder nichts), dann die Antwort des Servers, es sei denn, in der Zwischenzeit wurde ein neueres Abrufen gestartet.

9.3.7. Der Bildschirm

// =========================================================================
// lib/ex24_api_layer/main.dart - ein Terminkalender mit der API-Zugriffsschicht
// -------------------------------------------------------------------------
// Anmelden (obere Leiste), einen Arzt und einen Tag wählen:
// Der Terminkalender wird angezeigt. ADMIN und DOCTOR können für einen Patienten buchen und
// stornieren; ein Patient (martin...) bucht für sich selbst. Jede Aktion
// endet mit einem erneuten Lesen des Terminkalenders.
// Drei Schichten, von unten nach oben:
//   Api (common/api.dart)          die HTTP-Anfragen, die Fehler;
//   RdvMedecins (rdvmedecins.dart) eine typisierte Methode pro Route der API;
//   ScheduleModel (schedule_model.dart) der Zustand und die Aktionen des Bildschirms;
// und die View weiter unten, die nur das Modell anzeigt.
// =========================================================================

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: stellt ein gewöhnliches Objekt bereit (das nichts meldet)
        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: der Schlüssel, den der Server sendet, wenn ein Patient bereits einen bevorstehenden Termin hat
              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),
            ],
          ],
        ],
      ),
    );
  }
}

// eine Zeile des Terminkalenders: der Zeitraum, der Belegende, die erlaubten Buttons
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),
      // die Buttons folgen den vom Server berechneten Rechten
      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,
    );
  }
}
  • Zeilen 28–34: die drei Schichten, beim Start zusammengesetzt: [Api] (die Anfragen), [RdvMedecins] (die Routen), [ScheduleModel] (der Bildschirm). [Provider.value] stellt ein gewöhnliches Objekt bereit, das keine Benachrichtigungen auslöst;
  • Zeile 50: Die View abonniert das ViewModel;
  • Zeile 58: Die Anmeldeleiste benachrichtigt das Modell;
  • der Rest ist nur Anzeige: Jedes Widget liest den Zustand des Modells und ruft bei einer Benutzeraktion eine seiner Methoden auf ([model.chooseDoctor(id!)], [model.book(c)]...);
  • Zeilen 120–153: eine Zeile des Terminkalenders. Die Schaltflächen folgen den vom Server ([bookable], [appointmentId]) berechneten Berechtigungen.

Angemeldet als [admin], der Terminkalender von Frau PELISSIER; ein Zeitfenster wird für einen Patienten reserviert; angemeldet als [martin] (Rolle USER), derselbe Terminkalender:

Der Patient [martin] kann den Namen des Patienten für das reservierte Zeitfenster nicht sehen: Der Server hat ihn ihm nicht gesendet.

9.4. Beispiel 25: Vom Server zurückgegebene Fehler

9.4.1. Die Wörterbücher

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

Die Fehlermeldungen des Servers sind Schlüssel („ERRORS.LASTNAME_REQUIRED“): Das Wörterbuch übersetzt sie.

9.4.2. Der Bildschirm

// =========================================================================
// lib/ex25_server_errors/main.dart - Anzeige der Fehler des SERVERS
// -------------------------------------------------------------------------
// Die Verwaltung der Clients (Admin-Konto). Dieses Formular führt
// ABSICHTLICH keine Validierung auf dem Smartphone durch: Alles wird an den
// Server gesendet, der im Fall einer Ablehnung mit einem JSON-Fehler antwortet (von common/api.dart in einen
// ApiError umgewandelt):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (optimistisches Sperren)
//
// Der Fehler JEDES Felds (ApiError.fields) wird im Zustand gespeichert und
// unter dem Feld angezeigt (errorText); seine Meldung ist der vom Server gesendete SCHLÜSSEL,
// den der Bildschirm übersetzt (Wörterbücher aus Beispiel 21).
// Das Ändern eines Felds löscht dessen Fehler.
// Probieren Sie: einen leeren Nachnamen, einen Titel "Dr", einen Namensvetter (Alice DURAND), ein
// bereits vergebenes Login (martin), denselben Datensatz auf zwei Geräten geändert...
// =========================================================================

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

// die Felder des Formulars
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 = [];

  // das Formular: _editedId == null -> Anlegen, sonst Aktualisieren
  int? _editedId;
  int _version = 0;
  String _title = 'Mr';
  final _texts = {
    for (final c in [Field.firstName, Field.lastName, Field.login, Field.password]) c: TextEditingController(),
  };
  // der Fehler jedes Felds (ein Übersetzungs-SCHLÜSSEL), vom Server zurückgegeben
  Map<String, String> _errors = {};
  // die allgemeine Meldung des letzten Fehlers und die eines Erfolgs (Schlüssel + Parameter)
  ApiError? _pageError;
  ({String key, Map<String, String> params})? _success;
  // Senden an den Server: ein Command (Beispiel 23), das anzeigt, ob es läuft
  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;
      // die zusammen mit dem Datensatz gelesene VERSION geht bei der Aktualisierung zurück: Hat jemand
      // den Datensatz inzwischen geändert, antwortet der Server mit 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(); // Formular geleert, Meldungen gelöscht...
      // ... außer dieser
      setState(
        () => _success = (key: key, params: {'name': '${client.firstName} ${client.lastName}', 'login': client.login ?? ''}),
      );
      await _reload();
    } on ApiError catch (e) {
      setState(() {
        _pageError = e; // die allgemeine Meldung
        _errors = e.fields; // der Fehler jedes Felds
      });
    }
  }

  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;

    // ein Eingabefeld mit seinem übersetzten Fehler (ein Schlüssel des Servers)
    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,
      ),
      // ein geändertes Feld: sein Fehler verschwindet
      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: [
          // die Sprache: ein 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,
                    ),
                    // ein Titel "Dr", den der Server ablehnen wird: um ERRORS.INVALID_TITLE zu sehen
                    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)),
                      ),
                    // die allgemeine Meldung und der HTTP-Status zum Verständnis
                    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),
                              ),
                            ],
                          ),
                        ),
                      ),
                  ],
                ),
              ),
            ),
          ],
        ],
      ),
    );
  }
}

Verwaltung der Patienten (Konto admin). Dieses Formular führt auf dem Smartphone keinerlei Validierung durch: Alles wird an den Server gesendet, der – bei einer Ablehnung – mit einem Fehler-JSON antwortet, das in [ApiError] umgewandelt wird.

  • Zeilen 37–43: die Übersetzungen aus Beispiel 21 unter Verwendung der Wörterbücher dieses Beispiels;
  • Zeile 77: der Fehler zu jedem Feld: ein Übersetzungsschlüssel, vom Server zurückgegeben;
  • Zeilen 79–82: die allgemeine Meldung zum letzten Fehler, die Erfolgsmeldung und das [Command] zum Senden an den Server (Beispiel 23);
  • Zeilen 126–131: Die aus dem Datensatz gelesene Version wird zusammen mit der Änderung aktualisiert: Hat in der Zwischenzeit jemand den Datensatz geändert, antwortet der Server mit einem 409 [CONCURRENT_UPDATE] (optimistisches Sperren);
  • Zeilen 141–162: der Speichervorgang: [POST /api/clients] (Erstellung) oder [PUT /api/clients/:id] (Aktualisierung). Wird der Vorgang abgelehnt, liefert [ApiError] eine allgemeine Fehlermeldung und den spezifischen Fehler zu jedem Feld;
  • Zeilen 188–198: ein Eingabefeld: Sein Fehler, ein Schlüssel des Servers, wird übersetzt und unter dem Feld angezeigt ([errorText]); beim Bearbeiten des Feldes verschwindet sein Fehler;
  • Zeilen 209–212: ein Menü in der oberen Leiste zur Sprachauswahl;
  • Zeile 257: ein Titel „Dr“, den der Server ablehnen wird: siehe [ERRORS.INVALID_TITLE];
  • Zeilen 291–302: die allgemeine, übersetzte Meldung und, zur Einordnung, der HTTP-Status und der Schlüssel.

Ein leeres Formular; ein Namensvetter („Alice DURAND“); dasselbe auf Französisch:

Probieren Sie auch: einen bereits vergebenen Benutzernamen ([martin]), einen ungültigen Benutzernamen („Jean M“) und denselben Datensatz, der auf zwei Geräten bearbeitet wird (oder in der App und mit [curl]).

Das Prinzip ist dasselbe wie bei allen Formularen der Fallstudie: Die Regeln liegen an EINER Stelle – dem Server; die App zeigt die Ergebnisse in der Sprache des Benutzers an.