Der Server lehnt einen Wert ab, den der Client akzeptiert hat; der Benutzer klickt auf „Speichern“ und sieht ein unerklärtes „Vorgang fehlgeschlagen“. Oder umgekehrt: Der Server akzeptiert stillschweigend ein Feld, das der Client nie geprüft hat, und ein fehlerhafter Datensatz verfälscht monatelang Berichte. In Geschäftsformularen von Unternehmen leben Validierungsregeln meist an drei Orten: im Formularcode im Browser, im API-Controller und in Datenbank-Constraints. Mit der Zeit driften sie auseinander. Im Folgenden zeigen wir am Code, wie Sie in Webanwendungen mit TypeScript Regeln in einem Schema bündeln, asynchrone und feldübergreifende Regeln umsetzen, mehrstufige Formulare aufbauen und Serverfehler dem Benutzer anzeigen.
Rollen von Client- und Servervalidierung
Die beiden Ebenen verfolgen unterschiedliche Ziele, und keine ersetzt die andere:
| Ebene | Zweck | Vertrauenswürdig? |
|---|---|---|
| Client | Schnelles Feedback, Vermeiden unnötiger Anfragen, Benutzerfreundlichkeit | Nein; umgehbar |
| Server (Anwendung) | Datenintegrität, Geschäftsregeln, Berechtigungsprüfung | Ja; einziger verbindlicher Entscheidungspunkt |
| Datenbank | Letzte Verteidigungslinie: NOT NULL, UNIQUE, CHECK, Fremdschlüssel | Ja; schützt auch vor Race Conditions |
Client-Validierung ist keine Sicherheitsmaßnahme. Die Anfrage lässt sich mit den Entwicklerwerkzeugen des Browsers, mit curl oder per Automatisierungsskript direkt an die API senden; JavaScript kann deaktiviert, Felder im DOM verändert werden. Der Browser ist nicht Ihr Rechner, sondern der des Benutzers. Der Server prüft jedes vom Client kommende Feld erneut, als wäre es nie validiert worden. Servervalidierung ist auch nicht nur Formatprüfung: Dass die gewählte abteilungId wirklich existiert und der Benutzer berechtigt ist, in dieser Abteilung einen Datensatz anzulegen, ist ebenfalls Aufgabe des Servers. Für die Sicherheitsdimension der Eingabevalidierung ist das OWASP Input Validation Cheat Sheet eine gute Referenz; Maßnahmen gegen böswillige automatisierte Einsendungen sind Thema des Leitfadens Spamschutz in Webformularen.
Schemabasierter Validierungsansatz
Bei schemabasierter Validierung werden Struktur und Regeln der Formulardaten einmal deklarativ definiert; dasselbe Schema läuft im Browser und auf dem Server, und auch der TypeScript-Typ wird aus dem Schema abgeleitet. Im Ökosystem werden dafür Zod, Valibot und Yup genutzt. Die Beispiele sind mit Zod geschrieben; da sich zwischen Hauptversionen einige API-Details geändert haben, prüfen Sie die Zod-Dokumentation der verwendeten Version.
// shared/schemas/beschaffung.ts — von Client und Server gemeinsam genutztes Modul
import { z } from 'zod';
export const beschaffungsantrag = z.object({
titel: z.string().trim().min(5, 'Der Titel muss mindestens 5 Zeichen lang sein').max(120),
betrag: z.coerce.number().positive('Der Betrag muss groesser als null sein'),
waehrung: z.enum(['TRY', 'EUR', 'USD']),
kostenstelle: z.string().regex(/^[A-Z]{2}-\d{4}$/, 'Format: AA-1234'),
liefertermin: z.coerce.date(),
beschreibung: z.string().trim().max(2000).optional(),
});
export type Beschaffungsantrag = z.infer<typeof beschaffungsantrag>;
Die praktischen Folgen: Der mit z.infer abgeleitete Typ wird im API-Client, in der Formularkomponente und im Server-Handler gemeinsam genutzt; wird ein Feld hinzugefügt, zeigt der Compiler die fehlenden Stellen. Transformationen wie trim() normalisieren die Daten, die so immer im selben Format beim Server ankommen. z.coerce wandelt Werte, die aus Formularfeldern als Text kommen, in Zahl oder Datum um. Hier gibt es eine Falle: Leerer Text wird mit Number('') zu 0; behandeln Sie daher bei numerischen Pflichtfeldern den leeren Wert separat. Ohne Prüfung erscheint ein Antrag mit Betrag null als „gültig“.
Auf dem Server validiert dasselbe Schema den Anfrage-Body. Ein nicht validierter Body gelangt nie in die Geschäftslogik:
// Server: Beispiel mit Next.js Route Handler
import { beschaffungsantrag } from '@/shared/schemas/beschaffung';
export async function POST(req: Request) {
const ergebnis = beschaffungsantrag.safeParse(await req.json());
if (!ergebnis.success) {
const feldFehler: Record<string, string[]> = {};
for (const issue of ergebnis.error.issues) {
const feld = issue.path.join('.') || '_form';
(feldFehler[feld] ??= []).push(issue.message);
}
return Response.json({ feldFehler }, { status: 422 });
}
const antrag = ergebnis.data; // typisierte und normalisierte Daten
// Berechtigungspruefung + Geschaeftsregeln + Speichern
}
Im Client nutzt React Hook Form dasselbe Schema mit zodResolver aus dem Paket @hookform/resolvers. Da Schemas in einem separaten Modul liegen, lässt sich leicht kontrollieren, dass serverspezifische Abhängigkeiten (Datenbank-Client, geheime Schlüssel) nicht ins Client-Bundle gelangen: Eine Lint-Regel, die Dateien unter shared/schemas nur den Import von zod und anderen Schemadateien erlaubt, schützt diese Grenze. Nutzen Sie Next.js Server Actions, läuft dasselbe Schema statt im Route Handler am Anfang der Aktionsfunktion; der Ablauf ändert sich nicht.
Asynchrone und feldübergreifende Regeln
Manche Regeln passen nicht in ein einzelnes Feld. Dass das Enddatum nach dem Beginn liegt, dass bei Auswahl „Sonstiges“ eine Beschreibung Pflicht ist oder dass ab einem bestimmten Betrag ein zweiter Genehmiger nötig ist, sind feldübergreifende Regeln. In Zod werden sie auf Objektebene mit refine geschrieben, und das Feld, an das der Fehler gebunden wird, wird mit path angegeben:
export const urlaubsantrag = z.object({
beginn: z.coerce.date(),
ende: z.coerce.date(),
art: z.enum(['jahresurlaub', 'sonderurlaub', 'sonstiges']),
beschreibung: z.string().trim().optional(),
})
.refine((d) => d.ende >= d.beginn, {
message: 'Das Enddatum darf nicht vor dem Beginn liegen',
path: ['ende'],
})
.refine((d) => d.art !== 'sonstiges' || (d.beschreibung?.length ?? 0) > 0, {
message: 'Bei Auswahl von „Sonstiges“ ist eine Beschreibung Pflicht',
path: ['beschreibung'],
});
Asynchrone Regeln (ob eine Steuernummer im System registriert ist, ob ein Benutzername frei ist) erfordern eine Anfrage an den Server. Im Client dienen sie nur der Benutzerfreundlichkeit: Sie laufen beim Verlassen des Feldes (onBlur) und mit kurzer Verzögerung (Debounce); bei jedem Tastendruck wird keine Anfrage gesendet. Die verbindliche Prüfung wird beim Absenden auf dem Server wiederholt, weil sich der Zustand zwischen beiden Prüfungen geändert haben kann. Bei Regeln wie Eindeutigkeit ist die letzte Absicherung der UNIQUE-Constraint in der Datenbank; die Anwendung muss den Constraint-Verstoß abfangen und dem betreffenden Feld mit einer verständlichen Meldung zuordnen. Ein roher SQL-Fehler geht nicht an den Benutzer.
Kennen Sie zwei in der Praxis häufige Verhaltensweisen. Erstens: Ein refine auf Objektebene läuft nicht, solange in einem der Felder ein Fehler auf Typebene besteht (fehlendes Pflichtfeld, ungültiges Datum); der Benutzer sieht den Fehler zur Datumsreihenfolge erst, nachdem er diese Felder korrigiert hat. Ist das nicht akzeptabel, lösen Sie die Prüfung im Client zusätzlich aus oder fassen Sie die Felder in einem Unterobjekt zusammen. Zweitens: Ein Zod-Schema mit asynchronem refine wird mit parseAsync oder safeParseAsync ausgeführt; das synchrone parse wirft in diesem Fall einen Fehler.
Zustand und Validierung in mehrstufigen Formularen
In individuellen Webanwendungen werden lange Prozesse wie Lieferantenregistrierung, Personaleinstellungsformular oder Angebotserstellung in mehrstufige Assistenten aufgeteilt. Drei Designentscheidungen bestimmen den Verlauf:
- Teilen Sie das Schema in Schritte, behalten Sie aber auch das Ganze. Jeder Schritt hat sein eigenes Schema; das Gesamtschema ist deren Vereinigung. Der Button „Weiter“ führt nur das Schema dieses Schritts aus, beim endgültigen Absenden und auf dem Server läuft das Gesamtschema. In Zod werden Objektschemas mit
extend(in Zod 3 auch mitmerge) zusammengeführt; damergein Zod 4 als veraltet markiert ist, sollteextendbevorzugt werden. Schrittübergreifende Regeln werden dem Gesamtschema hinzugefügt; da ein Schema mit angewendetemrefinenicht mehr erweitert werden kann, kommt zuerst das Zusammenführen, dannrefine. - Entscheiden Sie über den Ort des Entwurfs. Bei kurzen Assistenten genügt der Formularzustand in der Komponente. Bei langen Prozessen oder wenn Robustheit gegen Neuladen nötig ist, speichern Sie den Entwurf auf dem Server als Datensatz mit Status „Entwurf“; Browserspeicher ist für Formulare mit personenbezogenen Daten nicht geeignet. Die Neigung, Formularzustand in einen globalen Store zu verlagern, und Alternativen dazu diskutiert der Leitfaden Zustandsverwaltung in React.
- Bewahren Sie Daten beim Zurückgehen. Kehrt der Benutzer zum vorherigen Schritt zurück, dürfen seine Eingaben nicht verloren gehen. Beeinflusst eine im vorherigen Schritt geänderte Auswahl die Regeln späterer Schritte, werden die betreffenden Felder erneut validiert.
In einem Schritt eingegebene Informationen im nächsten Schritt erneut zu verlangen, ermüdet den Benutzer und widerspricht dem WCAG-2.2-Kriterium 3.3.7 Redundant Entry. Füllen Sie zuvor eingegebene Werte automatisch aus oder machen Sie sie auswählbar.
Serverfehler dem Benutzer anzeigen
Lehnt der Server einen Wert ab, der den Client passiert hat, muss der Fehler in einer für den Benutzer korrigierbaren Form und neben dem richtigen Feld erscheinen. Dafür ist ein vorhersehbarer Fehlervertrag zwischen API und Frontend Pflicht. Ohne Vertrag interpretiert jeder Bildschirm den Fehler anders. Im obigen Beispiel wurden der Statuscode 422 und nach Feldnamen gruppierte Meldungen verwendet; wird für HTTP-APIs ein standardisierter Fehler-Body gewünscht, können Sie das Format RFC 9457 (Problem Details for HTTP APIs) zugrunde legen und Feldfehler als Erweiterungsmitglied hinzufügen.
// Client: Serverfehler den Feldern von React Hook Form zuordnen
const onSubmit = async (daten: Beschaffungsantrag) => {
const antwort = await fetch('/api/beschaffung', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(daten),
});
if (antwort.status === 422) {
const { feldFehler } = await antwort.json();
for (const [feld, meldungen] of Object.entries(feldFehler)) {
setError(feld as keyof Beschaffungsantrag, { type: 'server', message: meldungen[0] });
}
return;
}
if (!antwort.ok) {
setError('root.server', { type: 'server', message: 'Speichern nicht moeglich, bitte versuchen Sie es erneut.' });
}
};
Bei der Fehleranzeige zu prüfen:
- Die Fehlermeldung wird per
aria-describedbymit dem Feld verknüpft, das Feld mitaria-invalid="true"markiert; rote Farbe allein genügt nicht. - Gibt es beim Absenden mehrere Fehler, setzen Sie eine Übersicht an den Formularanfang und verschieben den Fokus dorthin oder auf das erste fehlerhafte Feld.
- Die Meldung sagt, was falsch ist und wie es korrigiert wird: statt „Ungültiger Wert“ besser „Kostenstelle muss im Format AA-1234 sein“.
- Interne Fehlerdetails des Servers (SQL-Fehler, Stacktrace) werden nicht an den Benutzer weitergegeben; sie werden ins Serverlog geschrieben, dem Benutzer werden eine allgemeine Meldung und bei Bedarf eine Tracking-ID angezeigt. Der Support findet mit dieser ID den betreffenden Eintrag im Log.
- Zeigen Sie während des Tippens nicht bei jedem Tastendruck Fehler an, validieren Sie beim Verlassen des Feldes; nachdem ein Fehler einmal angezeigt wurde, ist eine sofortige Aktualisierung während der Korrektur akzeptabel.
Für Details zur barrierefreien Fehleranzeige siehe den Formularabschnitt im WCAG-2.2-Leitfaden für Entwickler.
Validierungs-Checkliste
- Für jedes Formular gibt es ein einziges Schema; Client und Server importieren es aus einem gemeinsamen Modul.
- Der Server validiert den Anfrage-Body vor der Geschäftslogik mit dem Schema; nicht validierte Daten gelangen nicht in die Serviceschicht.
- Nicht im Schema definierte Felder werden ignoriert oder abgelehnt (gegen das Risiko von Mass Assignment); Felder wie Rolle, Eigentümer oder Freigabestatus werden nicht vom Client übernommen.
- Textfelder haben eine maximale Länge; numerische Felder Unter- und Obergrenzen.
- Existenz von ID- und Referenzfeldern (Abteilung, Projekt, Kunde) und die Berechtigung des Benutzers darauf werden auf dem Server geprüft.
- Eindeutigkeits- und Beziehungsregeln sind auch durch Datenbank-Constraints geschützt; Constraint-Verstöße werden in feldbezogene Meldungen umgewandelt.
- Asynchrone Prüfungen sind per Debounce begrenzt und werden beim Absenden auf dem Server wiederholt.
- Der API-Fehlervertrag ist dokumentiert; Feldfehler und allgemeine Fehler werden getrennt transportiert.
- Fehlermeldungen sind barrierefrei mit den Feldern verknüpft und zeigen den Weg zur Korrektur.
- Bei Feldern mit personenbezogenen Daten wurden Aufbewahrungs- und Informationspflichten gesondert bewertet; das Thema behandelt der Leitfaden KVKK-konformes (bzw. DSGVO-konformes) Kontaktformular.
Entwickeln Sie Geschäftsformulare mit Freigabeabläufen, rollenbasierten Feldern und mehrstufigen Anträgen, entwerfen wir im Rahmen von Formular-, Antrags- und Freigabesystemen auch die Validierungsschicht von Anfang an.
Häufig gestellte Fragen
Muss auf dem Server erneut validiert werden, wenn es eine Client-Validierung gibt?
Ja. Die Client-Validierung dient nur der Benutzerfreundlichkeit; sie lässt sich mit Browserwerkzeugen oder einer direkten API-Anfrage leicht umgehen. Für Datenintegrität und Sicherheit erfolgt die verbindliche Prüfung immer auf dem Server.
Birgt die Verwendung desselben Schemas auf Client und Server ein Risiko?
Solange das Schemamodul keine serverspezifischen Abhängigkeiten enthält, nicht. Regeln, die eine Datenbankabfrage erfordern, gehören nicht in das gemeinsame Schema, sondern in einen zusätzlichen Validierungsschritt auf dem Server; sonst kann Servercode ins Client-Bundle gelangen.
Welcher HTTP-Statuscode sollte für Validierungsfehler verwendet werden?
Verbreitet sind 400 Bad Request und 422 Unprocessable Content. Entscheidend ist, dass der Code API-weit konsistent ist und feldbezogene Fehler im Antwort-Body in einer vorhersehbaren Struktur zurückkommen.
Sollte asynchrone Validierung bei jedem Tastendruck laufen?
Nein. Prüfungen, die Anfragen an den Server senden, sollten beim Verlassen des Feldes und mit kurzer Verzögerung laufen. Das Ergebnis dient nur der Information; die verbindliche Prüfung wird beim Absenden auf dem Server wiederholt.