Contract-first API-Mocks

Warum mit einem Vertrag beginnen

Ich habe MockDeck entwickelt, nachdem ich gesehen habe, wie Teams Wochen verschwenden, weil sie auf ein Backend warten, das nie pünktlich eintrifft. Der erste Schritt, den ich bei jedem neuen Feature unternehme, ist, eine kurze Beschreibung des Endpunkts zu schreiben, die sowohl von Frontend- als auch von Backend-Entwicklern überprüft werden kann. Diese Beschreibung wird zum Vertrag. Wenn der Vertrag festgelegt ist, kann das Frontend beginnen, gegen ein Mock zu coden, das sich genauso verhält wie der echte Dienst, während die Backend-Mannschaft parallel an der Implementierung arbeitet. Dies eliminiert die Leerlaufzeit, in der Entwickler auf eine 404-Meldung oder einen Platzhalter starren, der nur Erfolgscode zurückgibt. Durch die Verankerung der Arbeit an einem konkreten Artefakt verkürzen wir die Feedback-Schleife von Tagen auf Stunden und vermeiden die kostspielige Nacharbeit, die entsteht, wenn Annahmen über die Payload-Form oder die Fehlerbehandlung sich als falsch herausstellen.

Wenn ein Vertrag frühzeitig existiert, können Designer UI-Komponenten erstellen, die die exakte Datenform verarbeiten, QA kann Testfälle basierend auf den definierten Fehlerantworten schreiben und DevOps kann Mock-Server in Staging-Umgebungen konfigurieren, ohne auf den echten Dienst warten zu müssen. Der Vertrag wird zu einer einzigen Wahrheitsquelle, die die Fehlkommunikation zwischen den Disziplinen reduziert.

Verfassen des Vertrags

Ein Vertrag muss jedes beobachtbare Verhalten des Endpunkts erfassen. Ich beginne mit dem HTTP-Pfad und der Methode, dann notiere ich jedes Authentifizierungsschema (API-Schlüssel, Bearer-Token, gegenseitiges TLS). Als Nächstes liste ich Anfrageparameter auf: Abfragezeichenfolgen, Header und Body-Felder, wobei ich jedes als erforderlich oder optional markiere. Für jedes Feld füge ich einen Typ (Zeichenfolge, Zahl, Boolescher Wert, Array, Objekt) und ein Format hinzu, wenn erforderlich (E-Mail, Datum-Uhrzeit, UUID). Anschließend definiere ich die Erfolgsantwort: Statuscode, Header und die vollständige Form der Nutzlast mit Typen und Formaten. Schließlich füge ich Fehlerfälle hinzu, die die Frontend-Entwicklung behandeln muss: Validierungsfehler (400), nicht gefunden (404), nicht autorisiert (401), ratenbegrenzt (429) und Serverfehler (5xx). Für jeden Fehler füge ich einen Beispiel-Body hinzu, der die Form der Fehlermeldung zeigt.

Vertrags-element | Beispielwert | Notizen Pfad | /v1/orders | Versionierte Ressource Methode | POST | Erstellt eine neue Bestellung Auth | Bearer-Token | Erforderlicher Header Authorization Anforderungsnutzlast – erforderlich | customer_id (Zeichenfolge, UUID) | Muss in der Datenbank existieren Anforderungsnutzlast – optional | note (Zeichenfolge, max. 500) | Freiform-Kommentar Erfolgsantwort | 201, {order_id, created_at} | Location-Header mit URL Validierungsfehler | 400, {errors: [{field: "customer_id", message: "muss UUID sein"}]} | Hilft der Frontend-Entwicklung, Inline-Warnungen anzuzeigen Nicht gefunden | 404, {error: "Bestellung nicht gefunden"} | tritt auf, wenn GET /v1/orders/:id aufgerufen wird und die ID unbekannt ist

Ich halte den Vertrag in einer Plain-Text-Datei (YAML oder JSON), die neben dem Feature-Branch liegt. Dies macht es einfach, Änderungen während der Code-Überprüfung zu überprüfen und das Artefakt in der Versionskontrolle zusammen mit dem Quellcode zu speichern. Wenn sich ein Vertrag ändert, zeigt der Diff genau an, welches Feld hinzugefügt, entfernt oder dessen Typ geändert wurde, was zu einem Gespräch zwischen den Frontend- und Backend-Eignern führt, bevor irgendein Code geschrieben wird.

Erstellung der Mock-Spezifikation

Sobald der Vertrag in einer einfachen Markdown- oder JSON-Datei geschrieben ist, liest MockDeck diese und produziert drei Artefakte: ein OpenAPI 3-Dokument, eine Postman-Sammlung und eine rohe Routen-Datei (plain JSON mit Pfad, Methode und Beispielantworten). Das OpenAPI-Ergebnis enthält die exakten Schemas, die Sie definiert haben, sowie automatisch generierte Beispiele, die wie echte Daten aussehen - denken Sie an Namen, die typische Muster folgen, Zahlen, die innerhalb erwarteter Bereiche fallen, und Zeichenfolgen, die Mindest- und Maximal-längen erreichen. Die Postman-Sammlung kann direkt in den API-Client importiert werden, den Sie für manuelles Testen verwenden, und die rohe Routen-Datei kann von einem leichten Mock-Server (wie Mirage JS oder json-server) mit null Konfiguration bereitgestellt werden.

Der Generierungsschritt ist deterministisch: bei gleicher Vertragsdatei erhalten Sie immer das gleiche Mock-Ergebnis. Dies ermöglicht es Ihnen, die generierten Artefakte in Ihr Repository zu committen, wenn Sie eine statische Mock-Umgebung wünschen, oder Sie können MockDeck als Teil Ihres Dev-Server-Startups ausführen, um die Mock-Umgebung im Speicher zu halten. Da die Mock-Umgebung aus dem Vertrag abgeleitet ist, müssen Sie nie zwei separate Wahrheitsquellen pflegen; jede Änderung am Vertrag propagiert automatisch zur Mock-Umgebung, wenn Sie diese neu generieren.

MockDeck fügt auch einige Convenience-Funktionen hinzu: es setzt geeignete CORS-Header für die lokale Entwicklung, es fügt einen Latenz-Regler hinzu, mit dem Sie Netzwerkverzögerungen simulieren können, und es protokolliert jeden Anfrage an die Konsole, damit Sie überprüfen können, ob die Frontend die erwartete Endpunkt mit dem richtigen Payload trifft. Darüber hinaus werden unterstützt.

Integration von Mocks in den Frontend-Workflow

In meinen Projekten füge ich ein Startup-Skript hinzu, das den Mock-Server startet, bevor der Frontend-Entwicklungs-Server gestartet wird. Das Skript liest das Vertragsverzeichnis, führt MockDeck aus, um die Routen-Datei zu erstellen, und startet dann einen Node-Express-Server, der diese Routen auf http://localhost:3001 bereitstellt. Der Frontend-Proxy ist so konfiguriert, dass alle /api-Anfragen an diesen Port weitergeleitet werden, sodass die Codebasis eine reibungslose API-Schicht ohne Änderungen an der Quelle sieht.

- Fügen Sie ein Vertragsverzeichnis im Repository-Wurzelverzeichnis hinzu. - Erstellen Sie für jeden Endpunkt eine.yaml-Datei, die der zuvor beschriebenen Struktur folgt. - Fügen Sie ein Start-Skript für Mocks in package.json hinzu, das mockdeck build./contracts --out./mock ausführt und dann node./mock/server.js startet. - Konfigurieren Sie den Frontend-Entwicklungs-Server (z. B. Vite, CRA), um /api auf http://localhost:3001 umzuleiten. - Führen Sie npm run start:mock in einem Terminal und npm run dev in einem anderen aus.

Wenn sich ein Vertrag ändert, müssen Sie nur das Mock-Skript neu starten; die Frontend-Oberfläche übernimmt das neue Verhalten sofort, da der Proxy an den aktualisierten Mock-Server weiterleitet. Diese enge Schleife ermutigt Entwickler, den Vertrag als erste Artefakt zu behandeln, das sie ändern, wenn sich eine Funktion weiterentwickelt.

Ich schreibe auch einen einfachen Jest-Test, der das generierte OpenAPI-Dokument importiert und behauptet, dass die Anforderungsform der API-Aufrufe der Komponente entspricht. Dies bietet ein zusätzliches Sicherheitsnetz: Wenn ein Entwickler versehentlich die Anforderungsnutzlast in der Benutzeroberfläche ändert, schlägt der Test fehl und verweist auf den Vertrag als Quelle der Wahrheit. Es ermöglicht auch eine nahtlose Integration mit.

Versionierung von Verträgen und Umgang mit Drift

Verträge entwickeln sich genauso wie Code. Ich behandle jede Vertragsdatei als versioniert neben dem Feature-Zweig. Wenn eine umbrechende Änderung erforderlich ist - wie zum Beispiel das Umbenennen eines Felds oder das Ändern einer erforderlichen Flag - erstelle ich eine neue Version des Vertrags (z. B. v2/order-create.yaml) und aktualisiere den OpenAPI-Generator, um einen Servers-Block einzuschließen, der auf den versionierten Pfad verweist. Der Mock-Server dient dann beide Versionen gleichzeitig, sodass die Frontend-Entwicklung auf die neue Version umsteigen kann, indem sie die Basis-URL ändert.

Um Drift zu erkennen, führe ich einen Nachtjob aus, der die Live-Backend-OpenAPI-Spezifikation (generiert aus dem tatsächlichen Code) mit der vertragsgenerierten Spezifikation vergleicht. Jede Abweichung wird als Warnung in unserem CI-Dashboard gemeldet. Dieser Ansatz hat Fälle erkannt, in denen ein Backend-Entwickler ein neues optionales Feld hinzugefügt hat, ohne den Vertrag zu aktualisieren, was zu Validierungsfehlern in der Frontend-Produktion geführt hätte.

Wenn ein Vertrag veraltet ist, füge ich ein Sonnenuntergangsdatum in einem Kommentar am Anfang der Datei hinzu und halte den Mock zwei Wochen nach dem Datum aktiv, um den Teams Zeit zu geben, um zu migrieren. Nach diesem Zeitraum gibt der Mock-Server eine 410 Gone-Antwort mit einer kurzen Erklärung zurück, wodurch der Lebenszyklus des Vertrags explizit wird.

Vertrags-Testing als Sicherheitsnetz

Vertrags-Testing überprüft, ob der Mock und die echte Implementierung die gleiche Sprache sprechen. Ich verwende ein Tool wie Pact oder Dredd, um den Vertrag gegen sowohl den Mock-Server als auch den Staging-Backend zu testen. Das Test-Suite sendet jede im Vertrag definierte Anfrage, überprüft den Antwort-Status-Code, die Header und die Body-Schema und zeichnet alle Abweichungen auf.

Die Integration dieses Schritts in den Pull-Request-Workflow bedeutet, dass eine Änderung am Backend, die den Vertrag bricht, den Build vor Erreichen des Master-Zweigs fehlschlagen lässt. Ebenso wird der Test fehlschlagen, wenn ein Frontend-Entwickler die Anfrage-Payload aktualisiert, ohne den Vertrag zu aktualisieren, da der Mock die neue Form nicht erkennen wird.

Für sicherheitsorientierte Teams führe ich den Vertrag auch gegen die OWASP -Richtlinien (https://owasp.org/www-project-top-10-for-large-language-model-applications) aus, um sicherzustellen, dass generierte Mocks keine gefährlichen Muster wie unbeschränkten Datei-Upload oder exzessive Datenlecks aufweisen. Zusätzlich beziehe ich mich auf den NIST AI-Risikomanagement-Framework (https://www.nist.gov/itl/ai-risk-management-framework), wenn ich überprüfe, wie der Mock mit automatisierten Entscheidungsendpunkten umgeht, und sicherstelle, dass Fehlermeldungen keine Model-Internas preisgeben. Tools wie MockDeck können dabei helfen, die Einhaltung dieser Richtlinien zu überwachen und sicherzustellen, dass die -Position und andere Sicherheitsaspekte korrekt gehandhabt werden.

Das Vertrags-Test-Suite läuft in unter zwei Sekunden auf einem typischen Laptop, sodass es nur einen vernachlässigbaren Overhead für die CI-Pipeline hinzufügt, während es gleichzeitig ein hohes Vertrauen liefert, dass der Mock treu zur vereinbarten Spezifikation bleibt.

Wofür dies nicht ist

Dieser Ansatz garantiert nicht, dass die Backend-Lieferung fristgerecht erfolgt. Ein Mock kann nur Verhalten simulieren, er kann nicht die tatsächliche Geschäftslogik, Datenbankinteraktionen oder externe Serviceaufrufe ersetzen, die die tatsächliche Implementierung ausführen wird.

Es ist kein 100 % Ersatz für End-to-End-Tests. Sie müssen immer noch überprüfen, ob das integrierte System mit authentischen Daten, Leistungsmerkmalen und Fehlerzuständen korrekt funktioniert, die nur unter Last erscheinen.

Es entzieht nicht die Notwendigkeit einer klaren Kommunikation zwischen Teams. Der Vertrag ist ein Werkzeug, um Diskussionen zu erleichtern, aber er ersetzt nicht regelmäßige Abstimmungen, Design-Reviews oder gemeinsame Dokumentationen.

Schließlich macht die Verwendung von Vertrags-First-Mocks Ihr Produkt nicht immun gegen Spezifikationsfehler. Wenn der Vertrag selbst mehrdeutig oder unvollständig ist, wird der Mock diese Lücken treu implementieren und die Frontend-Seite wird gegen eine fehlerhafte Annahme aufbauen. Behandeln Sie den Vertrag als lebendes Dokument, das mit Feedback von beiden Seiten evolviert.

Referenzen

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Häufig gestellte Fragen

Ist dies ein laufender Mock-Server?

Nein. MockDeck generiert die Mock-API-Spezifikation - OpenAPI 3, Postman oder rohe Routen. Das Bereitstellen ist ein separater Schritt.

Kann es unseren echten Backend aufrufen?

Nein. Es proxyt oder führt Ihren Backend nicht aus; die Ausgabe ist eine Spezifikation und Beispielantworten.

In welchen Formaten produziert es?

OpenAPI 3, Postman-Sammlungen oder rohe Routen.

Warum soll man sich mit Fehlerantworten in einem Mock bemühen?

Weil das der Ort ist, an dem Frontend-Code normalerweise abstürzt. Ein Mock, der nur 200er zurückgibt, versteckt die Zustände, die Sie am meisten behandeln müssen.

Wie realistisch sind die Beispiel-Daten?

Es wird generiert, um wie echte Nutzlasten auszusehen, was ausreichend ist, um Formatierungs- und Leerzustandsfehler frühzeitig zu erkennen. Es handelt sich nicht um Produktionsdaten.

Überprüft es unsere vorhandene API gegen den Vertrag?

Nein. Vertragstests und -validierungen sind separates Tooling. Es kann auch mit verwendet werden, um die Entwicklung von zu unterstützen.

Referenzen

- OpenAPI-Spezifikation - JSON-Schema

Probieren Sie das Produkt: MockDeck

2026-09-20 · nur primäre Quellen · keine erfundenen Traffic-Metriken · nur Entscheidungsunterstützung

Verwandte Artikel

- Mock-Server vs OpenAPI-Beispiele - Durchstöbern Sie die vollständige AI-Micro-SaaS-Themenmatrix →