API-Vertragstests

1) Warum Vertragstests

Der Vertrag erfasst die Erwartungen des Kunden und die Versprechen des Anbieters: Routen/Methoden, Titel, Körperschemata, Status, Fehlersemantik und Einschränkungen. Ziel ist es, inkompatible Änderungen vor der Integration zu erfassen und Versionen sicher und ohne schwere E2E freizugeben.

2) Ansätze

Consumer-Driven Contracts (CDC): Der Kunde bildet Erwartungen (Pact und Analoga); Der Anbieter überprüft diese regelmäßig.
Spezifikation: Vertrag als eine einzige Quelle der Wahrheit (OpenAPI/Protobuf/GraphQL SDL); Tests validieren die Implementierung gegen die Spezifikation.
Event: Meldungsschemata (Avro/JSON Schema/Protobuf) + Kompatibilitätsregeln im Broker/Register.

3) HTTP/REST: Spezifikationsfluss

1. Vertrag: OpenAPI 3. x (Schemata, Beispiele, Codes).
2. Lint und Statik: Stil, Pflichtfelder, einheitliche Codes.
3. Validierung der Implementierung: Testgenerator gegen OpenAPI (schemathesis/Dredd-Ansatz) + manuelle Negative.
4. Schnappschüsse: Beispiele für Antworten, ETag-Semantik, Idempotenz-Überschriften erfassen.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (Pact-Ansatz)

1. Der Konsument schreibt den Test, bildet eine Paktdatei (Erwartungen).

2. Veröffentlichung im Broker (Artefakt).

3. Der Provider in CI hebt Service (oder Vertrag-Stand), verifiziert pact's.

4. Der Broker berechnet eine can-i-deploy Kompatibilitätsmatrix.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/Protobuf Verträge

Der Vertrag ist '.proto' mit der Versionierung von Paketen/Diensten.
Kompatibilität: Verwenden Sie keine Tags neu, fügen Sie nur neue mit optional hinzu, entfernen Sie nicht die verwendeten Felder; Zimmer reservieren.
Tests: Server/Client-Stabgenerierung, Vermietung von autogenerierten Fällen + Negative (unknown fields, size-limits).

6) Veranstaltungsverträge (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Kompatibilitätsrichtlinie: 'BACKWARD' (oft ausreichend) oder 'FULL'.
Producer-Tests: validiert die Meldung gegen die Regelung; Consumer-Tests: Akzeptiert die alte und die neue Version.
Invarianten: Idempotenzschlüssel, Reihenfolge/Wiederholbarkeit, Semantik der Deduplizierung.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Kompatibilität und Versionen

Backward-kompatible (empfohlenes Minimum): Fügen Sie optionale Felder hinzu, brechen Sie vorhandene nicht.
Vorwärtskompatibel: Verbraucher ignorieren unbekannte Felder.
Voll: beides.
Versionierung: 'path (/v1)', 'Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-Policy: Ausgabefenster (z.B. 90 Tage), Warnüberschriften/Ereignisse.

8) Negative und Fehler sind auch ein Vertrag

Standardisieren Sie die Codes: 400/401/403/404/409/422/429/5xx, Pflichtfelder 'code', 'message', 'trace _ id'.
Größen/Grenzen sind Teil des Vertrages (413/414/431).
Idempotenz: Wiederholungsverhalten (409 vs 201 same id).
Überschriften: „Retry-After“ bei 429/503, „Idempotency-Key“, „Content-Language“ usw.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Daten werden durch Vertrag verwaltet

Beispiele/Anprobe Antworten (examples) - live, validiert in CI.
Fixturen für CDC sind minimal, deterministisch.
Datengenerierung - eigenschaftsbasiert für Zahlen/Daten; aber nicht brechen die Stabilität der snapshots.

10) Pipeline in CI/CD (Referenz)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: Vertrag als Artefakt (Broker/Register).
3. Verify: Der Anbieter vertreibt CDC-Pakete/Spezifikationstests.
4. can-i-deploy gate: ohne grüne Matrix ist die Freigabe verboten.
5. Diff: Überprüft, ob die Änderungen kompatibel sind (semantic diff).
6. Bericht: JUnit/HTML, Liste der Verstöße/Definitionen.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Tools (nach Aufgabenklassen)

Lint/Validatoren: openapi-linters, protobuf-lint, avro-tools.
CDC: Pact-Familie/Broker, Spring Cloud Contract, Hoverfly (HTTP-Einträge/Repliken).
Spezifikation Läufer: schemathesis/Dredd-like approach, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (identifiziert Breaking-Änderungen).
Container: Testcontainer zum Anheben des Anbieters/Vertragsregals.

12) Antipatterns

„Special Doc“ getrennt vom Code → nicht synchron. Halten Sie den Vertrag in der Nähe des Dienstes.
Moki-Dienste von Drittanbietern anstelle eines Vertrags → Zerbrechlichkeit bei Upgrades.
Zufällige Antworten/Generierung ohne Bindung an das → Flake-Schema.
Ändern Sie die Feldtypen/Obligationen ohne Version.
Silent-Erweiterungen ohne Benachrichtigung/Deprection.
Keine negativen Verträge und Fehlercodes.

13) Spezifität von iGaming/Finanzen

Formalisieren Sie Geldfelder: 'amount' - decimal mit Skala, Währung - ISO-4217, Invarianten von Summen.
Zahlungs-/Webhook-Verträge: HMAC/mTLS, Anti-Replay („X-Timestamp“ -Fenster), Idempotenz, „Retry-After“.
Regionalität/Tenanten: Pflichtüberschriften „X-Tenant/X-Region“, Lokalisierung der Botschaften.
Ereignisse: unveränderliche Protokolle (Audit), Deduplizierungsschlüssel, Liefergarantien (in der ersten Zeit + idempotente Handler).

14) Beispiele für „Skelett“ -Tests

14. 1 Schemathesis-Stil (Pseudo)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Postman als Spezifikationsläufer

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 CDC Provider Verifikation (Pseudo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Checkliste Prod-Ready

• Verträge im Repository, CI validiert und veröffentlicht Artefakte.
• CDC ist für kritische Integrationen aktiviert; funktioniert broker/matrix „can-i-deploy“.
• Die Kompatibilitätsrichtlinie (HTTP/gRPC/Events) ist dokumentiert. automatische semantic-diff.
• Negative Verträge: Fehler, Größengrenzen, Idempotenz, 'Retry-After'.
• Die Testdaten sind deterministisch; Beispiele werden unterstützt.
• Versionierung und Deprecation: Fristen, Benachrichtigungen, Überschriften.
• Für Ereignisse - Schema Registry und Kompatibilitätsmodus; Der Producer/Consumer testet beide Versionen.
• Artefakte: JUnit/HTML, diff/verify reports, Kompatibilitätsmatrix.
• Incident-procedure: quick rollback contract/fitch-flag, notification to integrators.

16) TL; DR

Erfassen Sie die Erwartungen in Verträgen und fahren Sie sie automatisch ab: CDC für Kundenerwartungen, Spezifikationstests für die Einhaltung der Implementierung, Scheme-Register für Ereignisse. Halten Sie strenge Kompatibilitätsrichtlinien und negative Verträge (Fehler, Limits, Idempotenz) ein. Sie können nicht ohne grüne Can-i-Deploy-Matrix und semantic-diff ohne Breaking-Änderungen veröffentlichen.