Vertragsprüfung

1) Wo Verträge anzuwenden sind

HTTP REST/JSON: Ressourcen, Paginierung, Filter, Idempotenz, Fehlercodes.
gRPC/Protobuf: Nachrichtentypen, Status, Semantik 'deadline', backward-compat v.proto.
GraphQL: Schemas, Non-Null, Direktiven, Permishens zu Feldern.
Nachrichten/Streams (Kafka/Pulsar/SQS): Event-Schemas (Avro/JSON/Protobuf), Partitionierungsschlüssel, Reihenfolge, idempotente Schlüssel.
Interne SDKs/Bibliotheken: öffentliche Funktionen/Ausnahmen/Leistungsverträge.

2) CDC-Modell: Rollen und Artefakte

Der Verbraucher veröffentlicht den Erwartungsvertrag (beispielhafte Anfragen/Antworten, Typmatcher, Invarianten).
Der Lieferant setzt die Verifizierung der Verträge gegen seinen Service/Adapter/Handler durch.
Der Contract Broker (Pact Broker/Backstage/Artefakt-Repo) speichert Versionen, Tags ('prod',' staging', 'canary') und die Kompatibilitätsmatrix' consumer @ v → provider @ v'.
Freigaberichtlinie: Die Entsendung eines Anbieters ist verboten, wenn ein „prod-relevanter“ Vertrag verletzt wird.

3) Was im Vertrag festgelegt werden soll (HTTP-Beispiel)

• Methode/Pfad/Parameter/Header (inkl. auth, idempotenter Schlüssel).
• Körper und typische Spieler (Typ/Format/Regeccp/Bereiche).
• Fehlercodes und -struktur; stabile' error _ code'.
• Semantische Invarianten: Sortierung, Einzigartigkeit, Monotonie' created _ at'.
• Nicht-funktionale Erwartungen (optional): p95, Größenlimits, Rate-Limit-Header.

json
{
"interaction": "GET /v1/users/{id}",
"request": { "method": "GET", "path": "/v1/users/123", "headers": {"Accept":"application/json"} },
"matchers": {
"response.body.id": "type:number",
"response.body.email": "regex:^.+@.+\\..+$",
"response.body.created_at": "format:rfc3339"
},
"response": {
"status": 200,
"headers": {"Content-Type":"application/json"},
"body": {"id": 123, "email": "alice@example.com", "created_at": "2025-10-31T12:00:00Z"}
},
"error_cases": [
{
"name":"not_found",
"request":{"path":"/v1/users/9999"},
"response":{"status":404, "body":{"error_code":"USER_NOT_FOUND"}}
}
]
}

4) Verträge für Veranstaltungen (eventgetrieben)

Schema des Ereignisses: 'type', 'version', 'id', 'occurred _ at _ utc', 'producer', 'subject', 'payload'.
Invarianten: Unveränderlichkeit 'id' und Idempotenz durch'(type, id)', Ordnung innerhalb des Parteitaktes, Monotonie' sequence'.
Schema Registry: Speichert die Evolution und Kompatibilitätsregeln (backward/forward/full).
Consumer Contract Tests: Replizieren „goldene“ Ereignisse und Phasen von Negativen (unbekannte Felder, nullbar).

json
{
"type":"record","name":"UserRegistered","namespace":"events.v1",
"fields":[
{"name":"id","type":"string"},
{"name":"occurred_at_utc","type":{"type":"long","logicalType":"timestamp-millis"}},
{"name":"email","type":"string"},
{"name":"marketing_opt_in","type":["null","boolean"],"default":null}
]
}

5) Evolution und Kompatibilität

Vertragsversionen: Semantik 'MAJOR. MINOR. PATCH'(MAJOR - brechend).

• Nicht brechen: Felder nicht löschen, Typ/Wert von 'error _ code' nicht ändern.
• Fügen Sie optionale Standardfelder hinzu; neue Endpoints statt „Magie“.
• Deprection: Ankündigung, parallele Unterstützung, Entfernung durch Metriken.
• GraphQL: Felder nur hinzufügen, Non-Null durch Phasen eingeben; Richtlinien der Deprektion.
• gRPC/Proto: Feldnummern nicht überverwenden; nur neue mit optional hinzufügen.
• Ereignisse: Regelung „vN“; Verbraucher sind verpflichtet, unbekannte Felder zu ignorieren (Faulheit).

6) Negative und invariante Prüfungen

Negativ: falsche Typen, verbotene Werte, Konfliktparameter, Überschreitung von Limits.
Invarianten: Sortierung der Antworten, Eindeutigkeit 'id', Korrektheit 'next _ cursor', Stabilität der idempotenten Antwort bei Wiederholung.
Verträge mit Zeitaspekten: „created _ at“ RFC3339/UTC, die korrekte Projektion des lokalen Tages ist nicht Teil des Transportvertrags - wird in geschäftliche Invarianten übertragen.

7) Generierung und lokale Entwicklung

Aus den Verträgen werden Pakete des Anbieters generiert, um den Verbraucher zu entwickeln.
Für Ereignisse - Generatoren von „validen/grenzwertigen“ Nachrichten nach dem Schema.
Die Stapel sind mit der Vertragsversion und dem Montagedatum gekennzeichnet; Die Veröffentlichung in prod ist untersagt.

8) Einbettung in CI/CD (Referenz-Pipeline)

1. Consumer CI:

Lint/Montage → Vertragserstellung → Unit/Vertragstests → Veröffentlichung im contract-broker (tag: 'consumer @ 1. 7. 0`).

2. Provider CI:

Anhebung des Dienstes lokal/im Container → Fatch relevanter Verträge ("Prod'/" Staging") → Überprüfung → Veröffentlichung des Status im Broker.

3. Release Gate:

Das Deploy des Anbieters wird gesperrt, wenn noch ausstehende Verträge vorliegen.

4. Nightly Matrix:

Kompatibilitätsmatrix „consumer versions × provider versions“; Berichte und Alarme.

9) Beispiele für Domain-basierte Praktiken

9. 1 REST: Paginierung durch Cursor (vertragliche Invariante)

Die Antwort enthält 'items []', 'next _ cursor' (nullbar), 'limit', 'total' (optional).
Invarianten: 'len (items) ≤ limit', Rückruf mit dem gleichen 'cursor' → idempotent set.
Fehler, wenn 'cursor' und 'page' gleichzeitig gesetzt sind.

9. 2 POST-Idempotenz

Der Vertrag verlangt die Überschrift „Idempotency-Key“.
Invariante: Eine wiederholte Abfrage mit dem gleichen Schlüssel gibt den gleichen 'id '/Status zurück.

9. 3 Veranstaltungen: Garantien der Ordnung

Partitionierungsschlüssel im Vertrag: 'partition _ key = user_id'.
Invariant: 'sequence' wächst monoton innerhalb des Schlüssels; Der Consumer ist verpflichtet, Wiederholungen zu verarbeiten.

10) Sicherheit und Privatsphäre in Verträgen

PDs/Geheimnisse nicht in die Beispiele aufnehmen - nur synthetisch.
Obligatorische Sicherheitsüberschriften erfassen: 'Authorization', 'X-Signature', 'Replay-Prevention'.
Für Webhooks gibt es einen Unterschriften- und Antwortvertrag '2xx '/Retrays.
In den Protokollen der Vertragstests steht die Maskierung empfindlicher Felder.

11) Werkzeuge

Pact/Pactflow/Pact Broker - HTTP/Message-Verträge, Kompatibilitätsmatrix.
OpenAPI/AsyncAPI - Spezifikationen + Testgeneratoren (Dredd, Schemathesis).
Karate/REST Assured - Szenarioprüfungen von REST-Verträgen.
Protobuf/gRPC - 'buf', 'protolint', Interoperabilitätstests; Schema Registry für Avro/JSON/Proto in Threads.
Konformitätstests für GraphQL (graphql-compat), Snapshot-Schaltungstests.

12) Pseudocode der Anbieterverifizierung (vereinfacht)

python def verify_contract(provider, contract):
for case in contract["cases"]:
req = build_request(case["request"])
res = provider.handle(req) # локально/контейнер assert match_status(res.status, case["response"]["status"])
assert match_headers(res.headers, case["response"].get("headers", {}))
assert match_body(res.body, case["matchers"], allow_extra_fields=True)
for neg in contract.get("error_cases", []):
res = provider.handle(build_request(neg["request"]))
assert res.status == neg["response"]["status"]
assert res.json.get("error_code") == neg["response"]["body"]["error_code"]

13) Anti-Muster

„Postman Screenshots is a contract“: keine Versionen/typische Matchmaker/automatische Validierung.
Überschneidung: Der Vertrag erfasst genaue Werte anstelle von Typen/Mustern → Fehleinschätzungen.
Ein gemeinsamer Vertrag für verschiedene Regionen/Kanäle: ignoriert die Variabilität (Flags, Geo-Regeln).
Verträge ohne Broker/Matrix: Es ist nicht nachvollziehbar, welche Versionen kompatibel sind.
Wetten auf e2e statt Verträge: langsam, teuer, instabil.
Keine negativen/invarianten Fälle: Nur der „grüne Weg“ wird getestet.

14) Beobachtbarkeit und Betrieb

Export des Status in Broker + Dashboard „Gesundheitsverträge“.
Alertas: Neue Drops des Anbieters gegen 'prod' -Verträge, das Wachstum des „unbekannten Feldes“ in den Ereignissen.
Ablaufverfolgung: 'contract _ id', 'version', 'decision _ id' in den Verifizierungsprotokollen.

15) Deprecationsprozess

1. Feld/Endpunkt hinzufügen (nicht brechen).
2. Markieren Sie das Alte als' deprecated 'in der Spezifikation, kündigen Sie Fristen an.
3. Verfolgen Sie die Verbraucher nach Logs/Broker; Migrationsbewegungen.
4. Aktivieren Sie „shadow“ deny in stage (dry-run), dann enforce.
5. Löschen Sie nach Null-Nutzung und Kompatibilitätsbestätigung.

16) Checkliste des Architekten

1. Sind Verbraucher und ihre Eigentümer definiert? Werden Verträge versioniert?
2. Gibt es einen Broker und eine Matrix für die Kompatibilität mit Medien-Tags?
3. Sind Negative und Invarianten (Idiempotenz, Cursor, Sortierung) im Vertrag enthalten?
4. Schema Registry und Kompatibilitätsmodus für Ereignisse konfiguriert?
5. Blockiert Pipeline die Freigabe des Anbieters, wenn Prod-Verträge verletzt werden?
6. Wird der Deprektionsprozess und die Politik der Evolution beschrieben?
7. Stapel aus Verträgen werden generiert, gibt es lokale Event-Generatoren?
8. Sind die PD-Maskierung und die obligatorischen Sicherheitsüberschriften dokumentiert?
9. Metriken/Alerts für Verträge sind verbunden, gibt es Drift-Berichte?
10. Werden Verträge im CI bei beiden Parteien (Consumer und Provider) geprüft?

Schluss

Vertragstests übertragen die „Wahrheit“ über Interaktionen in versionierbare Artefakte und machen Integrationen vorhersehbar. CDC, der Vertragsbroker und die Disziplin der Scheme-Evolution ersetzen „Breaking Surprise“ durch einen überschaubaren Prozess: schnelle Checks, klare Invarianten und transparente Versionskompatibilität. Dies reduziert die Kosten von e2e, beschleunigt Releases und verbessert die Qualität der gesamten Plattform.