Typsichere Express-APIs mit Zod und OpenAPI in einem Vertrag

Dieser Leitfaden erstellt erneut einen nutzbaren Weg zur Erstellung einer typsicheren Express-API mit Zod und OpenAPI. Der Fokus liegt auf Verträgen, Überprüfungen sowie Code, den man ohne Rückschluss auf die Absicht direkt in ein Repository einfügen kann. Zur Übersicht sollten Sie vor dem Ändern des Codes die Eingaben, den Verantwortlichen für den Schritt sowie die Abbruchkriterien definieren. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckten Zustände schließen zu müssen. Ziehen Sie kleine, testbare Einheiten vor großen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf.

Die Idee

Für die Idee sollten Sie vor dem Ändern des Codes die Eingaben, den Verantwortlichen für den Schritt sowie die Abbruchkriterien definieren. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Betrachten Sie diese Phase als Vertrag zwischen den Eingaben und den validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Validieren Sie an den Grenzen mithilfe von Schemata, die auch Dokumentation erzeugen. Eine einzige Quelle der Wahrheit verhindert Abweichungen zwischen OpenAPI und den Handlern.

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

api.post("/users", {
  body: CreateUserSchema,
  response: {
    201: UserSchema,
  },
  handler: async (req) => {
    const user = await createUser(req.body);
    return {
      status: 201,
      body: user,
    };
  },
});

Warum eine weitere Express-Bibliothek entwickeln?

Zu der Frage „Warum eine weitere Express-Bibliothek bauen?“ sollten vor dem Ändern des Codes die Eingabedaten, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckten Zuständen schließen zu müssen. Zeiten und Kosten sollten neben den funktionalen Ergebnissen aufgezeichnet werden. Frühzeitige Sichtbarkeit verhindert überraschende Rechnungen, wenn der Weg von einer Demo-Umgebung in gemeinsam genutzte Umgebungen wechselt. Validieren Sie an den Grenzen mithilfe von Schemata, die gleichzeitig Dokumentation erzeugen. Eine einzige Quelle der Wahrheit vermeidet Abweichungen zwischen OpenAPI und den Handlern.

Der aktuelle Stand

Für den aktuellen Stand sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definiert werden. Operator:innen sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Die Konfiguration sollte außerhalb des Anwendungscode gespeichert werden. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort zusammengefasst sein, den Operator:innen überprüfen können, ohne den gesamten Ablauf durchzulesen. Überprüfen Sie an den Grenzen mithilfe von Schemata, die gleichzeitig Dokumentation erzeugen. Eine einzige Quelle der Wahrheit verhindert Abweichungen zwischen OpenAPI und den Handlern. Für den aktuellen Stand sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definiert werden. Operator:innen sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Ziehen Sie kleine, testbare Einheiten vor großen, komplexen Skripten vor. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf.

Ihnen wäre Feedback von Entwicklern sehr willkommen

Weil Ihnen Feedback von Entwicklern sehr willkommen ist, sollten Sie die Eingaben, den Verantwortlichen für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definieren. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf verborgene Zustände schließen zu müssen. Betrachten Sie diese Phase als Vertrag zwischen den Eingaben und den validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Geben Sie strukturierte Fehler zurück, auf die sich die Kunden stützen können. Eine strenge Typisierung von Fehlern zwingt zum Raten.

Operative Checkliste

Für die operative Checkliste sollten Sie die Eingaben, den Verantwortlichen für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definieren. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf verborgene Zustände schließen zu müssen.

Dokumentieren Sie den erfolgreichen Ablauf sowie den Wiederherstellungsprozess gemeinsam. Versuche, menschliche Eingriffe und die Handhabung von Fehlern gehören zum Produkt selbst, nicht zu späteren Optimierungen.

Geben Sie strukturierte Fehler zurück, auf die sich die Clients stützen können. Fehlertypisierungen ohne strenge Regeln zwingen zum Raten.

Ziehen Sie langweilige Zuverlässigkeit vor cleveren, einmaligen Demonstrationen.

Ziehen Sie kleine, testbare Einheiten vor umfangreiche Skripte. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf.

Geben Sie strukturierte Fehler zurück, auf die sich die Clients stützen können. Fehlertypisierungen ohne strenge Regeln zwingen zum Raten.

Vor der Einführung des Stack-Systems sollten Sie Versionen einfrieren, ein „goldenes Protokoll“ für den kritischen Ablauf erstellen und die Rollback-Schritte überprüfen. Gemeinsame Umgebungen benötigen Rate Limits, Überprüfungen der Nutzerrechte sowie einen klaren Verantwortlichen für die Rotation von Geheimnissen. Ziehen Sie langweilige Zuverlässigkeit vor cleveren, einmaligen Demonstrationen.