Kontrakt-først API-mocks

Hvorfor starte med en kontrakt

Jeg byggede MockDeck efter at have set hold waste uger på at vente på en backend, der aldrig ankom på tid. Det første skridt, jeg tager med enhver ny funktion, er at skrive en kort beskrivelse af endpointet, som både frontend- og backend-udviklere kan gennemgå. Denne beskrivelse bliver kontrakten. Når kontrakten er fastsat, kan frontend-teamet starte med at kode mod en mock, der opfører sig præcis som den rigtige service vil, mens backend-teamet arbejder på implementeringen i parallel. Dette eliminerer den inaktive periode, hvor udviklere stirrer på en 404 eller en placeholder, der kun returnerer succes-koder. Ved at fæste arbejdet til en konkrekt artefakt, reducerer vi feedback-loopet fra dage til timer og undgår den kostbare om-arbejdning, der sker, når antagelser om payload-form eller fejlhåndtering viser sig at være forkerte.

Når en kontrakt findes tidligt, kan designere oprette UI-komponenter, der forbruger den præcise data-form, QA kan skrive test-tilfælde baseret på de definerede fejl-svar, og DevOps kan konfigurere mock-servers i staging-miljøer uden at vente på den rigtige service. Kontrakten bliver en enkelt kilde til sandhed, der reducerer misforståelser på tværs af discipliner.

Skriver kontrakten

En kontrakt skal fange hver observerbar adfærd i endpointet. Jeg starter med HTTP-stien og metoden, derefter noterer jeg eventuelle godkendelsesskemaer (API-nøgle, bærertoken, gensidig TLS). Herefter listar jeg anmodningsparametre: forespørgselssæt, overskrifter og bodyfelter, og markerer hver som påkrævet eller valgfrit. For hvert felt tilføjer jeg en type (streng, nummer, boolesk, array, objekt) og et format, hvis nødvendigt (e-mail, dato-klokkeslæt, uuid). Jeg definerer herefter succes-svaret: statuskode, eventuelle overskrifter og den fulde form af payloaden med typer og formater. Til sidst tilføjer jeg fejltilfælde, som frontend skal håndtere: valideringsfejl (400), ikke fundet (404), ikke autoriseret (401), ratebegrænsning (429) og serverfejl (5xx). For hver fejl inkluderer jeg et eksempel på en fejlmeddelelse, der viser formen på fejlmeldingen.

Kontraktelement | Eksempelværdi | Noter Sti | /v1/orders | Versioneret ressource Metode | POST | Opretter en ny ordre Godkendelse | Bærertoken | Påkrævet overskrift Authorization Anmodningsbody – påkrævet | customer_id (streng, uuid) | Skal eksistere i DB Anmodningsbody – valgfrit | note (streng, maks 500) | Fritformat kommentar Succes-svar | 201, {order_id, created_at} | Location-overskrift med URL Valideringsfejl | 400, {errors: [{field: "customer_id", message: "skal være uuid"}]} | Hjælper frontend med at vise inline-advarsler Ikke fundet | 404, {error: "ordre ikke fundet"} | Forekommer på GET /v1/orders/:id, når id er ukendt

Jeg gemmer kontrakten i en plain-text-fil (YAML eller JSON), der ligger ved siden af funktionsgrenen. Dette gør det let at diff ændringer under kodereview og at gemme artefakten i versionskontrol sammen med kildekoden. Når en kontrakt ændres, viser diff præcis, hvilket felt der er tilføjet, fjernet eller har ændret sin type, hvilket udløser en samtale mellem frontend- og backend-ejere, før nogen kode skrives.

Generering af mock-specifikation

Når kontrakten er skrevet i en simpel markdown- eller JSON-fil, læser MockDeck den og producerer tre artefakter: et OpenAPI 3-dokument, en Postman-samling og en rå ruter-fil (ren JSON med sti, metode og eksempel-svar). OpenAPI-udgangen indeholder de eksakte skemaer, du definerede, samt automatisk genererede eksempler, der ligner rigtige data - tænk på navne, der følger typiske mønstre, numre, der falder inden for forventede områder, og strengte, der rammer minimum- og maksimumlængder. Postman-samlingen kan importeres direkte til den API-klient, du bruger til manuel test, og den rå ruter-fil kan betjenes af en letvægts mock-server (såsom Mirage JS eller json-server) med nul konfiguration.

Genereringstrinet er deterministisk: givet den samme kontraktfil får du altid det samme mock-udgang. Dette giver dig mulighed for at committe de genererede artefakter til din repository, hvis du ønsker en statisk mock, eller du kan køre MockDeck som en del af din dev-server-start for at holde mock'en i hukommelsen. Fordi mock'en er afledt af kontrakten, behøver du aldrig at vedligeholde to separate kilder til sandheden; enhver ændring af kontrakten vil automatisk propagere til mock'en, når du regenererer.

MockDeck tilføjer også en few bekvemmelighedsfunktioner ud af boksen: den sætter passende CORS-headers for lokal udvikling, den tilføjer en forsinkelsesregulator, så du kan simulere netværksforsinkelse, og den logger hver anmodning til konsollen, så du kan verificere, at frontend rammer den forventede slutpunkt med den korrekte payload. Det kan også bruges med følge retningslinjerne i

Integrering af mocks i frontend-arbejdsgangen

I mine projekter tilføjer jeg et startup-script, der starter mock-serveren før frontend-udviklingsserveren. Scriptet læser kontrakt-mappen, kører MockDeck for at producere ruter-filen og starter derefter en node-express-server, der betjener disse ruter på http://localhost:3001. Frontend-proxyen er konfigureret til at videregive alle /api-anmodninger til denne port, så kodebasen ser en glat API-lag uden ændringer i kildekoden.

- Tilføj en contracts-mappe i repo-roden. - For hvert endpoint opret en.yaml-fil, der følger den struktur, der er beskrevet tidligere. - Tilføj et start:mock-script i package.json, der kører mockdeck build./contracts --out./mock og derefter node./mock/server.js. - Konfigurer frontend-udviklingsserveren (f.eks. Vite, CRA) til at videregive /api til http://localhost:3001. - Kør npm run start:mock i en terminal og npm run dev i en anden.

Når en kontrakt ændres, skal du kun genstarte mock-scriptet; frontend-picken op den nye funktion med det samme, fordi proxyen videregive til den opdaterede mock-server. Denne tætte løkke opmuntrer udviklere til at behandle kontrakten som den første artefakt, de ændrer, når en funktion udvikles.

Jeg skriver også en simpel Jest-test, der importerer den genererede OpenAPI-dokument og påstår, at anmodningsformen matcher komponentens API-opkald. Dette giver en ekstra sikkerhedsnet: hvis en udvikler utilsigtet ændrer anmodningsnyttelasten i brugergrænsefladen, mislykkes testen og peger på kontrakten som kilde til sandheden.

Versionsaftaler og håndtering af drift

Kontrakter udvikler sig ligesom kode. Jeg behandler hver kontraktfil som versionsstyring sammen med funktionsgrenen. Når der er behov for en breaking change - f.eks. omdøbning af et felt eller ændring af en påkrævet flag - opretter jeg en ny version af kontraktet (f.eks. v2/order-create.yaml) og opdaterer OpenAPI-generatoren til at inkludere en servers-blok, der peger på den versionsstyrede sti. Mock-serveren serverer herefter både versioner samtidig, hvilket giver frontend-mulighed for at vælge den nye kontrakt ved at ændre base-URL'en.

Til at registrere drift kører jeg en natlig opgave, der sammenligner live-backendens OpenAPI-specifikation (genereret fra den faktiske kode) med kontrakt-genereret specifikation. Enhver afvigelse rapporteres som en advarsel i vores CI-dashboard. Denne tilgang har fanget tilfælde, hvor en backend-udvikler tilføjede et nyt valgfrit felt uden at opdatere kontraktet, hvilket ville have forårsaget frontend-valideringsfejl i produktion.

Når en kontrakt er forældet, tilføjer jeg en solnedgangsdato i en kommentar i toppen af filen og holder mock'en aktiv i to uger efter datoen for at give holdene tid til at migrere. Efter denne periode returnerer mock-serveren en 410 Gone-svar med en kort forklaring, hvilket gør kontraktens livscyklus eksplicit.

Kontrakttestning som sikkerhedsnet

Kontrakttestning verificerer, at mocken og den virkelige implementering taler det samme sprog. Jeg bruger et værktøj som Pact eller Dredd til at køre kontrakten mod både mock-serveren og staging-backend. Testssuiten sender hver anmodning defineret i kontrakten, checker svarkodens status, header og bodieskema, og optager eventuelle afvigelser.

At inkorporere dette trin i pull request-workflow betyder, at en ændring i backend, der bryder kontrakten, vil fejle bygningen, før den når master. På samme måde, hvis en frontend-udvikler opdaterer anmodningsnyttelasten uden at opdatere kontrakten, vil testen fejle, fordi mocken ikke vil kunne genkende den nye form.

Til sikkerhedsfokuserede hold kører jeg også kontrakten mod OWASP -retningslinjerne (https://owasp.org/www-project-top-10-for-large-language-model-applications) for at sikre, at genererede mocks ikke uforvarende eksponerer farlige mønstre, såsom ubegrænset filoverførsel eller overmål af dataleakage.

Kontrakttestssuiten kører på under to sekunder på en typisk laptop, så den tilføjer næsten ingen overhead til CI-pipeline, mens den leverer høj tillid til, at mocken forbliver tro mod den aftalte specifikation. Det er også vigtigt at nævne, at jeg samarbejder med andre herunder for at sikre, at vores løsninger er i overensstemmelse med MockDeck og andre standarder.

Hvad dette ikke er

Denne tilgang garanterer ikke, at backenden bliver leveret på tid. En mock kan kun simulere adfærd; den kan ikke erstatte den faktiske forretningslogik, databaseinteraktioner eller eksterne servicekald, som den rigtige implementering vil udføre.

Det er ikke en 100 % erstatning for end-to-end-test. Du skal stadig verificere, at det integrerede system fungerer korrekt med ægte data, performanceskarakteristika og fejltilstande, der kun kan optræde under belastning.

Det fjerner ikke behovet for tydelig kommunikation mellem hold. Kontrakten er et værktøj til at faciliterer diskussion, men den erstattter ikke regelmæssige sync-opkald, design-gennemgang eller fælles dokumentation.

Endelig vil brug af kontrakt-først-mocks ikke gøre dit produkt immunt over for specifikationsfejl. Hvis kontrakten i sig selv er tvetydig eller ufuldstændig, vil mocken trofast implementere disse huller, og frontend vil bygge på en fejlbehæftet antagelse. Behandle kontrakten som et levende dokument, der udvikler sig med feedback fra begge sider.

Referencer

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

Ofte stillede spørgsmål

Er dette en kørende mock-server?

Nej. MockDeck genererer mock-API-specifikationen - OpenAPI 3, Postman eller rå ruter. At betjene den er et separat trin.

Kan det ringe vores rigtige backend?

Nej. Den proxy'er eller kører ikke din backend; outputtet er en specifikation og eksempelsvar.

Hvilke formater producerer det?

OpenAPI 3, Postman-samlinger eller rå ruter.

Hvorfor besvær med fejlbeskeder i en mock?

Fordi det er der, hvor frontend-koden normalt fejler. En mock, der kun returnerer 200'er, skjuler de tilstande, du har mest brug for at håndtere.

Hvor realistisk er eksempeldata?

Det er genereret for at se ud som rigtige payload, hvilket er nok til at fange formaterings- og tom-tilstandsfejl tidligt. Det er ikke produktionsdata.

Validerer det vores eksisterende API mod kontrakten?

Nej. Kontrakttest og validering er separate værktøj.

Referencer

- OpenAPI Specification - JSON Schema

Prøv produktet: MockDeck

2026-09-20 · kun primære kilder · ingen fabrikerede trafikmetrikker · beslutningsstøtte kun

Relaterede artikler

- Mock-servers vs OpenAPI-eksempler - Udforsk det fulde AI mikro-SaaS emne matrix →