Ein TypeScript-Typ prüft deinen Quellcode, aber keinen fremden JSON-Inhalt. Eine API-Grenze benötigt einen Laufzeitparser. HTTP liefert außerdem Statuscodes. Ein 500-Ergebnis ist oft eine erfolgreich empfangene Response mit einem fachlich oder technisch gescheiterten Request. Unser Beispiel prüft deshalb sowohl Status als auch Datenform. Typed API Contract Kit bündelt solche Regeln in wiederverwendbaren Verträgen.
01Unbekannte Daten prüfen
parseEntry nimmt unknown entgegen. Erst nachdem Objekt, ID und Titel geprüft sind, entsteht ein Entry. Das ist etwas anderes als JSON.parse(...) as Entry. Eine Assertion führt keine Prüfung aus.
type Entry = { id: string; title: string };
function parseEntry(value: unknown): Entry {
if (typeof value !== 'object' || value === null ||
!('id' in value) || typeof value.id !== 'string' ||
!('title' in value) || typeof value.title !== 'string') {
throw new Error('Invalid entry response');
}
return { id: value.id, title: value.title };
}
async function loadEntry(response: Response): Promise<Entry> {
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return parseEntry(await response.json());
}
async function main() {
console.log(await loadEntry(Response.json({ id: 'e1', title: 'Roof' })));
try { await loadEntry(Response.json({ id: 'e1' })); }
catch (error) { console.log(String(error)); }
}
void main();
Starten / prüfen
npx tsc contract.ts --strict --target ES2022 --module NodeNext
node contract.js02Die Transportgrenze kapseln
loadEntry bekommt eine Response, prüft ok und verarbeitet dann JSON als unknown. Im Beispiel erzeugen wir Responses lokal. Eine echte Fetch-Funktion würde davor die Adresse und ein AbortSignal erhalten.
03Fehlerklassen unterscheiden
Ein Netzwerkabbruch, ein Status 500 und eine Antwort ohne title benötigen unterschiedliche Diagnoseinformationen. Für Nutzer können sie zu klaren, übersetzten Meldungen führen. Kein Fehler darf ungeprüfte Daten in den bestätigten Zustand übertragen.
04Projektumfang korrekt lesen
Der geprüfte Contract-Kit-Stand implementiert Parser, Fastify-Adapter und Fetch-Client. React-Query-Integration, OpenAPI-Erzeugung und Kompatibilitäts-CLI stehen noch auf der Roadmap. Ein Tutorial darf geplante Funktionen nicht als fertige APIs darstellen.
Die gültige Response liefert Roof. Eine fehlende title-Eigenschaft wird abgewiesen.
Deine Übung
Ergänze einen nicht leeren Titel als Fachregel. Teste danach Status 500 und einen leeren Titel.
Lösung mit Erklärung anzeigen
Prüfe value.title.trim().length nach der Typprüfung. Ein 500-Ergebnis scheitert vor dem Parser. Ein leerer Titel scheitert innerhalb des Parsers. Diese Reihenfolge trennt HTTP- und Datenfehler.
Projektbezug und Quellen
Das Beispiel ist zum Lernen vereinfacht. Die verlinkte Codeversion zeigt die Anwendung im Projekt und die dortigen Prüfungen.