Skip to content

5. Die HTTP-Funktionen in Dart

Image

5.1. Auswahl der HTTP-Werkzeuge

Anders als JavaScript/TypeScript, das eine NATIVE Funktion [fetch] bereitstellt (sowohl im Browser als auch in Node.js), bietet Dart in seiner Standardbibliothek KEINEN High-Level-Client ([dart:io] stellt nur einen Low-Level-[HttpClient] bereit, der sich direkt nur umständlich verwenden lässt). Zwei externe Pakete decken zusammen genau dasselbe Gebiet ab wie [fetch] und [axios] im TypeScript-Kurs:

  • [package:http] (pub.dev/packages/http), vom Dart-Team selbst gepflegt: eine einfache Low-Level-API ohne globale Konfiguration und ohne Interceptors — die Rolle von [fetch].
  • [package:dio] (pub.dev/packages/dio): globale Konfiguration ([baseUrl], [timeout]), Interceptors, erweiterte Fehlerbehandlung ([DioException.response]) — die Rolle von [axios].

5.2. Der Steuerberechnungsserver

Alle Skripte in diesem Kapitel zielen auf den im vorigen Kapitel installierten NestJS-Server unter der Adresse [http://localhost:3000/main.php]. Vergewissern Sie sich vor dem Testen der folgenden Skripte, dass Ihr NestJS-Server läuft. Damit er funktioniert, muss auch das Tool Laragon laufen.

5.2.1. Skript [dart_fetch_01]

// dart_fetch_01.dart
// Portiert fetch-01.ts.
// Wahl der HTTP-Werkzeuge in Dart: das Paket [http] (pub.dev/packages/http),
// vom Dart-Team selbst gepflegt, spielt die Rolle des nativen [fetch] von
// Node.js/dem Browser - eine einfache, low-level API, ohne
// globale Konfiguration oder Interceptors (anders als das Paket [dio],
// das die Rolle von [axios] spielt - siehe dart_dio_01.dart).
import 'dart:convert';
import 'package:http/http.dart' as http;

// Basis-URL des Steuerberechnungsservers (siehe Kapitel
// "Installation eines NestJS-Servers")
const String baseUrl = 'http://localhost:3000/main.php';

// Sitzung initialisieren
Future<dynamic> initSession() async {
  // [Unterschied zu TypeScript] Das Paket [http] hat keine Option
  // [timeout] für die Anfrage selbst: Wir begrenzen die Wartezeit, indem wir
  // das Future mit der Erweiterung [.timeout(...)] von dart:async umhüllen,
  // die auf JEDES Future funktioniert (nicht nur auf HTTP-
  // Anfragen) - ein allgemeinerer Mechanismus als fetchs
  // AbortSignal.timeout(), das speziell für das native fetch gilt.
  final uri = Uri.parse(baseUrl).replace(queryParameters: {
    'action': 'init-session',
    'type': 'json',
  });
  try {
    // asynchrone Anfrage - http.get() liefert ein Future<http.Response>
    final stopwatch = Stopwatch()..start();
    final response = await http.get(uri).timeout(const Duration(seconds: 2));
    // [response] ist die gesamte HTTP-Antwort des Servers (HTTP-
    // Header + Body) - wir geben sie aus, um ihre Struktur zu sehen
    print("http response in Dart (duration=${stopwatch.elapsedMilliseconds}ms) : "
        "statusCode=${response.statusCode}");
    // wir können auf die HTTP-Header zugreifen
    print("response headers=${response.headers}");
    // [Unterschied zu TypeScript] Anders als bei fetch, wo response.json()
    // eine eigene ASYNCHRONE Methode ist (ein neues Future), steht der Body der
    // http.Response bereits vollständig
    // SYNCHRON zur Verfügung (response.body, ein String): http.get() hat bereits auf
    // den ganzen Body gewartet, bevor es sein Ergebnis liefert. jsonDecode() ist daher
    // hier keine asynchrone Operation.
    final object = jsonDecode(response.body);
    print("json response=$object, type=${object.runtimeType}");
    return object;
  } catch (error) {
    // wir sind hier, weil der Server mit einem Fehlercode geantwortet hat oder
    // weil der http-Client eine Exception ausgelöst hat (Netzwerk nicht erreichbar,
    // Timeout überschritten...)
    print("fetch error in Dart=${error.runtimeType}, $error");
    // wir werfen den Fehler erneut
    rethrow;
  }
}

// die Funktion main führt die asynchrone Funktion [initSession] aus
Future<void> main() async {
  try {
    print("HTTP request to the server in progress "
        "---------------------------------------------");
    final response = await initSession();
    print("success ---------------------------------------------");
    print("response=$response ${response.runtimeType}");
  } catch (error) {
    print("error ---------------------------------------------");
    print("error=$error");
  }
}

Kommentieren wir diesen Code:

  • Zeile 30: [http.get(uri).timeout(const Duration(seconds: 2))]: Das Paket [http] hat keine Option [timeout] für die Anfrage selbst - Wir begrenzen die Wartezeit, indem wir das [Future] mit der Methode [.timeout(...)] von dart:async umhüllen, die für JEDES [Future] funktioniert, nicht nur für HTTP-Anfragen.
  • Zeile 43: [jsonDecode(response.body)]: Anders als bei [fetch], wo [response.json()] eine eigene ASYNCHRONE Methode ist, steht der Body einer [http.Response] bereits vollständig SYNCHRON zur Verfügung ([response.body], ein [String]): [http.get()] hat bereits auf den gesamten Body gewartet, bevor es sein Ergebnis zurückgibt.

Das Ergebnis der Ausführung lautet:

1
2
3
4
5
6
HTTP request to the server in progress ---------------------------------------------
http response in Dart (duration=73ms) : statusCode=200
response headers={x-powered-by: Express, connection: keep-alive, keep-alive: timeout=5, set-cookie: connect.sid=s%3AWxLD5aAAWVIL6pinZyP75L4COQi837LW.NmwJehFDFeCvZ0p6CKHV9ybz9xNUvndTB7TYlKgp7s4; Path=/; HttpOnly; SameSite=Lax, date: Sun, 20 Sep 2026 09:47:30 GMT, content-length: 84, etag: W/"54-sE02l73cr4dRIJSanYxwhuhm21c", content-type: application/json; charset=utf-8}
json response={action: init-session, status: 700, response: session started with type [json]}, type=_Map<String, dynamic>
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]} _Map<String, dynamic>

5.2.2. Skript [dart_fetch_02]

// dart_fetch_02.dart
// Portiert fetch-02.ts: "knappe" Version von dart_fetch_01.dart, ohne die
// Zwischenausgaben.
import 'dart:convert';
import 'package:http/http.dart' as http;

const String baseUrl = 'http://localhost:3000/main.php';

// Sitzung initialisieren
Future<dynamic> initSession() async {
  final uri = Uri.parse(baseUrl).replace(queryParameters: {
    'action': 'init-session',
    'type': 'json',
  });
  final response = await http.get(uri).timeout(const Duration(seconds: 2));
  // in jSON empfangenes Ergebnis
  return jsonDecode(response.body);
}

// die Funktion main führt die asynchrone Funktion [initSession] aus
Future<void> main() async {
  try {
    print("HTTP request to the server in progress "
        "---------------------------------------------");
    final response = await initSession();
    print("success ---------------------------------------------");
    print("response=$response");
  } catch (error) {
    print("error ---------------------------------------------");
    print("error=$error");
  }
}

Kommentieren wir diesen Code:

  • Eine knappe Version von dart_fetch_01.dart ohne die Zwischenausgaben — die Struktur bleibt dieselbe: [Uri] konstruieren, [http.get] aufrufen, JSON dekodieren.

Das Ergebnis der Ausführung lautet:

1
2
3
HTTP request to the server in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]}

5.2.3. Skript [dart_fetch_03]

// dart_fetch_03.dart
// Portiert fetch-03.ts: maximale Wartezeit und manueller Abbruch einer HTTP-
// Anfrage.
import 'package:http/http.dart' as http;

// Basis-URL des Steuerberechnungsservers (siehe http/README, der
// historische PHP-Server des ursprünglichen Kurses; hier zielen wir direkt auf den
// NestJS-Server - siehe Kapitel "Installation eines NestJS-Servers")
const String baseUrl = 'http://localhost:3000/main.php';

// Beispiel 1: Anfrage mit maximaler Wartezeit dank [.timeout(...)]
// (Erweiterung von dart:async auf jedes Future - siehe dart_fetch_01.dart)
Future<void> requestWithMaximumDelay() async {
  print("--- request with .timeout() ---");
  try {
    final response = await http
        .get(Uri.parse('$baseUrl?action=init-session&type=json'))
        // nach 2 Sekunden schließt [.timeout] das Future mit einem Fehler ab,
        // nämlich einer [TimeoutException] - das Dart-Äquivalent zu
        // fetchs AbortSignal.timeout()
        .timeout(const Duration(seconds: 2));
    print("response = ${response.body}");
  } catch (error) {
    // wenn der Server nicht existiert (in dieser Übung wahrscheinlich) oder wenn
    // die Wartezeit überschritten wird, ist [error] je nach Fall eine [TimeoutException] oder eine
    // [SocketException]/[ClientException]
    print("error.runtimeType = ${error.runtimeType}, message = $error");
  }
}

// Beispiel 2: manueller Abbruch einer Anfrage, zum Beispiel weil
// der Benutzer es sich anders überlegt hat (z. B. er tippt in einem Suchfeld
// neu).
//
// [WARNUNG, grundlegender Unterschied zu TypeScript] Das Paket [http] hat kein
// Abbruchsignal PRO ANFRAGE wie fetchs AbortSignal: Der
// einzige Weg zum Abbrechen ist, den CLIENT ZU SCHLIESSEN (http.Client.close()),
// was ALLE laufenden Anfragen dieses Clients abbricht - man muss
// daher einen eigenen Client für die Anfrage anlegen, die man
// einzeln abbrechen können möchte, statt eines Clients, der von der ganzen Anwendung gemeinsam genutzt wird.
Future<void> manuallyCancellableRequest() async {
  print("--- request cancelled manually ---");
  final client = http.Client();

  // wir planen einen "fachlichen" Abbruch nach 10 ms (in einer echten
  // Anwendung wäre das zum Beispiel ein Klick auf eine Schaltfläche "Abbrechen")
  Future.delayed(const Duration(milliseconds: 10), () {
    print("manual cancellation triggered");
    client.close();
  });

  try {
    final response = await client.get(Uri.parse('$baseUrl?action=init-session&type=json'));
    print("response = ${response.body}");
  } catch (error) {
    // das Schließen des Clients während einer laufenden Anfrage lässt sie mit
    // einer [ClientException] fehlschlagen
    print("error.runtimeType = ${error.runtimeType}, message = $error");
  }
}

Future<void> main() async {
  await requestWithMaximumDelay();
  await manuallyCancellableRequest();
}

Analysieren wir diesen Code:

  • Zeile 21: [.timeout(const Duration(seconds: 2))] schließt das fehlgeschlagene [Future] mit einer [TimeoutException] ab, wenn das Zeitlimit überschritten wurde - das Dart-Äquivalent zu [AbortSignal.timeout()] bei [fetch].
  • Zeile 35: [WARNING, key difference] — das Paket [http] hat KEIN Abbruchsignal PRO ANFRAGE wie [AbortController] bei [fetch]: Die einzige Möglichkeit zum Abbrechen besteht darin, den Client ([http.Client.close()]) vollständig zu SCHLIESSEN, was ALLE ausstehenden Anfragen dieses Clients abbricht — daher die Notwendigkeit, einen EIGENEN Client für die Anfrage zu erstellen, die Sie einzeln abbrechen können möchten.

Das Ergebnis der Ausführung lautet:

1
2
3
4
5
--- request with .timeout() ---
response = {"action":"init-session","status":700,"response":"session started with type [json]"}
--- request cancelled manually ---
response = {"action":"init-session","status":700,"response":"session started with type [json]"}
manual cancellation triggered

5.2.4. Skript [dart_dio_01]

// dart_dio_01.dart
// Portiert axios-01.ts und axios-02.ts.
// Wahl der HTTP-Werkzeuge in Dart: das Paket [dio] (pub.dev/packages/dio)
// spielt die Rolle von [axios] - globale Konfiguration (baseUrl, timeout),
// Interceptors, erweiterte Fehlerbehandlung (error.response, wie
// bei axios): alles, was das Paket [http], das näher an fetch ist, dem
// aufrufenden Code überlässt (siehe dart_fetch_01.dart).
import 'package:dio/dio.dart';

// eine einmal für alle konfigurierte Dio-Instanz, die von allen
// Aufrufen wiederverwendet wird - genau die Rolle von "axios.defaults" in TypeScript
final Dio dio = Dio(BaseOptions(
  baseUrl: 'http://localhost:3000/',
  connectTimeout: const Duration(seconds: 2),
  receiveTimeout: const Duration(seconds: 2),
));

// Sitzung initialisieren
Future<dynamic> initSession({required String type}) async {
  try {
    // asynchrone Anfrage - dio.get() akzeptiert direkt
    // queryParameters, wie axios.request({params: ...})
    final response = await dio.get('main.php', queryParameters: {
      'action': 'init-session',
      'type': type,
    });
    // die Antwort des Servers steht in [response.data] (von Dio bereits in
    // Map/List dekodiert, wenn der Content-Type JSON ist), genau wie
    // response.data bei axios
    return response.data;
  } on DioException catch (error) {
    // der Parameter [error] ist eine [DioException] - wir geben sie aus, um
    // ihre Struktur zu sehen (Äquivalent zum auskommentierten "console.log(axios error)"
    // in axios-01.ts)
    if (error.response != null) {
      // der Server hat im HTTP-Status einen Fehler gemeldet, aber
      // auch eine Antwort gesendet: Sie steht in [error.response!.data],
      // genau wie [error.response.data] bei axios
      return error.response!.data;
    } else {
      // überhaupt keine Antwort (Netzwerk nicht erreichbar, Timeout...) - wir
      // werfen den Fehler erneut
      rethrow;
    }
  }
}

Future<void> main() async {
  try {
    // 1. Versuch, absichtlich ungültig (type='x' statt 'json'),
    // um zu beobachten, wie der Server - dann dio - den Fehler melden:
    // Der Server antwortet trotzdem (mit einem fachlichen Fehlerstatus), daher
    // ist error.response.data tatsächlich gefüllt, wie in axios-01.ts
    print("HTTP request (invalid type) to the server in progress "
        "---------------------------------------------");
    final invalidResponse = await initSession(type: 'x');
    print("response=$invalidResponse ${invalidResponse.runtimeType}");

    // 2. Versuch, korrigiert (type='json'), wie axios-02.ts
    print("HTTP request (corrected type) to the server in progress "
        "---------------------------------------------");
    final response = await initSession(type: 'json');
    print("success ---------------------------------------------");
    print("response=$response ${response.runtimeType}");
  } catch (error) {
    print("error ---------------------------------------------");
    print("error=$error");
  }
}

Analysieren wir diesen Code:

  • Zeilen 12–15: [Dio(BaseOptions(baseUrl: ..., connectTimeout: ..., receiveTimeout: ...))]: eine einmalig und endgültig konfigurierte [Dio]-Instanz, die von allen Aufrufen wiederverwendet wird — genau die Rolle von [axios.defaults] in TypeScript.
  • [response.data]: die Antwort des Servers, die von Dio bereits in [Map]/[List] DEKODIERT wurde, wenn der [Content-Type] JSON ist, genau wie [response.data] in axios.
  • Zeilen 30–31: [on DioException catch (error) { if (error.response != null) ... }]: dieselbe Unterscheidung wie bei [error.response] in Axios zwischen einem Fehler MIT Serverantwort (fachlicher Fehlerstatus) und einem Fehler OHNE Antwort (Netzwerk nicht erreichbar, Timeout).

Das Ergebnis der Ausführung lautet:

1
2
3
4
5
HTTP request (invalid type) to the server in progress ---------------------------------------------
response={action: init-session, status: 703, response: invalid parameter type=[x]} _Map<String, dynamic>
HTTP request (corrected type) to the server in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]} _Map<String, dynamic>

5.2.5. Skript [dart_dio_02]

// dart_dio_02.dart
// Portiert axios-03.ts: Verkettung zweier HTTP-Anfragen - init-session, dann
// authenticate-user (ein POST mit einem als
// x-www-form-urlencoded kodierten Body).
import 'package:dio/dio.dart';

final Dio dio = Dio(BaseOptions(
  baseUrl: 'http://localhost:3000/',
  connectTimeout: const Duration(seconds: 2),
  receiveTimeout: const Duration(seconds: 2),
));

Future<dynamic> initSession() async {
  try {
    final response = await dio.get('main.php', queryParameters: {
      'action': 'init-session',
      'type': 'json',
    });
    return response.data;
  } on DioException catch (error) {
    if (error.response != null) {
      return error.response!.data;
    }
    rethrow;
  }
}

Future<dynamic> authenticateUser(String user, String password) async {
  try {
    // POST-Anfrage mit einem x-www-form-urlencoded-Body - Dio kodiert eine Map automatisch
    // als x-www-form-urlencoded, wenn der
    // Content-Type in den [Options] angegeben ist, genau wie qs.stringify(...)
    // + der manuelle Header in axios-03.ts
    final response = await dio.post(
      'main.php',
      queryParameters: {'action': 'authenticate-user'},
      data: {'user': user, 'password': password},
      options: Options(contentType: Headers.formUrlEncodedContentType),
    );
    return response.data;
  } on DioException catch (error) {
    if (error.response != null) {
      return error.response!.data;
    }
    rethrow;
  }
}

// die Funktion main führt die asynchronen Funktionen nacheinander aus
Future<void> main() async {
  try {
    // init-session
    print("init-session action in progress "
        "---------------------------------------------");
    final response1 = await initSession();
    print("success ---------------------------------------------");
    print("response=$response1");
    // authenticate-user - [HINWEIS, wie im ursprünglichen TypeScript-
    // Kurs] Dieser Aufruf startet mit einer neuen HTTP-Anfrage, OHNE
    // das Sitzungs-Cookie, das der Server im
    // vorherigen Schritt gesetzt hat, automatisch zu übernehmen (weder Dio noch axios tun das automatisch auf
    // der Node-/Dart-Seite): Die manuelle Verwaltung des Sitzungs-Cookies ist genau
    // das Thema von dart_dio_03.dart, das axios-04.ts portiert.
    print("authenticate-user action in progress "
        "---------------------------------------------");
    final response2 = await authenticateUser('admin', 'admin');
    print("success ---------------------------------------------");
    print("response=$response2");
  } catch (error) {
    print("error ---------------------------------------------");
    print("error=$error");
  }
}

Analysieren wir diesen Code:

  • Zeile 38: [Options(contentType: Headers.formUrlEncodedContentType)]: Dio kodiert die an [data] übergebene [Map] automatisch als [x-www-form-urlencoded], sobald dieser [Content-Type] angegeben ist - das Äquivalent zu [qs.stringify(...)] in Kombination mit dem manuellen Axios-Header.
  • Dieser Aufruf ist eine neue HTTP-Anfrage, die das vom Server im vorherigen Schritt gesetzte Sitzungs-Cookie NICHT automatisch mitverwendet — weder Dio noch axios tun dies auf Dart-/Node-Seite automatisch: Die manuelle Verwaltung der Cookies ist Thema des folgenden Skripts.

Das Ergebnis der Ausführung lautet:

1
2
3
4
5
6
init-session action in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]}
authenticate-user action in progress ---------------------------------------------
success ---------------------------------------------
response={action: authenticate-user, status: 103, response: [no session in progress. Start with action [init-session]]}

5.2.6. Skript [dart_dio_03]

// dart_dio_03.dart
// Portiert axios-04.ts: manuelle Verwaltung des Sitzungs-Cookies zwischen zwei Anfragen.
import 'package:dio/dio.dart';

final Dio dio = Dio(BaseOptions(
  baseUrl: 'http://localhost:3000/',
  connectTimeout: const Duration(seconds: 2),
  receiveTimeout: const Duration(seconds: 2),
  // wir deaktivieren die Standardvalidierung des HTTP-Status, um eine Fehlerantwort
  // selbst untersuchen zu können (wie error.response bei
  // axios), ohne systematisch einen catch-Block zu durchlaufen
  validateStatus: (_) => true,
));

// Sitzungs-Cookie
const String sessionCookieName = "connect.sid";
String sessionCookie = '';

Future<dynamic> getRemoteData(String path, {
  required String method,
  Map<String, dynamic>? queryParameters,
  Object? data,
  Options? options,
}) async {
  // für das Sitzungs-Cookie - wir fügen es selbst in die Header
  // jeder Anfrage ein, genau wie axios-04.ts
  final opts = (options ?? Options(method: method)).copyWith(
    method: method,
    headers: {
      ...?options?.headers,
      'Cookie': sessionCookie,
    },
  );
  // Ausführung der HTTP-Anfrage
  final response = await dio.request(
    path,
    queryParameters: queryParameters,
    data: data,
    options: opts,
  );
  // wir lesen das Sitzungs-Cookie aus, falls vorhanden - response.headers ist ein
  // Dio-Objekt [Headers] (keine einfache Map wie response.headers bei
  // axios); response.headers['set-cookie'] liefert eine List<String>?
  final setCookie = response.headers['set-cookie'];
  if (setCookie != null) {
    // wir suchen das Sitzungs-Cookie in dieser Liste
    for (final header in setCookie) {
      final result = RegExp('^($sessionCookieName.+?);').firstMatch(header);
      if (result != null) {
        // wir speichern das Sitzungs-Cookie
        sessionCookie = result.group(1)!;
        break;
      }
    }
  }
  // die Antwort des Servers steht in [response.data]
  return response.data;
}

Future<dynamic> initSession() {
  return getRemoteData(
    'main.php',
    method: 'GET',
    queryParameters: {'action': 'init-session', 'type': 'json'},
  );
}

Future<dynamic> authenticateUser(String user, String password) {
  return getRemoteData(
    'main.php',
    method: 'POST',
    queryParameters: {'action': 'authenticate-user'},
    data: {'user': user, 'password': password},
    options: Options(contentType: Headers.formUrlEncodedContentType),
  );
}

// die Funktion main führt die asynchronen Funktionen nacheinander aus
Future<void> main() async {
  try {
    print("init-session action in progress ----------------");
    final response1 = await initSession();
    print("success --------------------------");
    print("response=$response1");
    print("authenticate-user action in progress ---------");
    final response2 = await authenticateUser('admin', 'admin');
    print("success -------------------");
    print("response=$response2");
  } catch (error) {
    print("error ------------------");
    print("error=$error");
  }
}

Analysieren wir diesen Code:

  • Zeile 12: [validateStatus: (_) => true]: deaktiviert die standardmäßige Validierung des HTTP-Status, sodass Sie eine Fehlerantwort selbst untersuchen können, ohne immer einen [catch]-Block durchlaufen zu müssen — dieselbe Entscheidung wie in axios-04.ts.
  • [response.headers['set-cookie']] liefert eine [List<String>?]: Anders als [response.headers] in Axios (ein einfaches Objekt) ist [response.headers] in Dio ein eigenes [Headers]-Objekt, dessen Indizierung immer eine Liste liefert.
  • Zeile 48: [RegExp('^($sessionCookieName.+?);').firstMatch(header)]: Das Sitzungs-Cookie wird manuell ausgelesen und gespeichert und dann in den [Cookie]-Header jeder folgenden Anfrage wieder eingefügt — exakt dasselbe Muster wie in axios-04.ts, angepasst an die API von Dio.

Das Ergebnis der Ausführung lautet:

1
2
3
4
5
6
init-session action in progress ----------------
success --------------------------
response={action: init-session, status: 700, response: session started with type [json]}
authenticate-user action in progress ---------
success -------------------
response={action: authenticate-user, status: 200, response: Authentication successful [admin, admin]}

5.2.7. Fazit

[package:http] und [package:dio] decken zusammen den gesamten Umfang von [fetch] und [axios] ab: eine Low-Level-API nahe am Protokoll und eine funktionsreiche API mit globaler Konfiguration und erweiterter Fehlerbehandlung. Die spezifischen Unterschiede ([timeout] ist generisch pro [Future] statt pro Anfrage, es fehlt ein individueller Abbruch, es fehlt eine automatische Cookie-Verwaltung) werden sich in den HTTP-Clients des folgenden Kapitels konkret niederschlagen.