5. Die HTTP-Funktionen in Dart

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:
| 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:
| 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:
| --- 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:
| 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:
| 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:
| 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.