Testarea contractelor

1) În cazul în care se aplică contracte

HTTP REST/JSON: resurse, paginare, filtre, idempotență, coduri de eroare.
gRPC/Protobuf: tipuri de mesaje, stări, semantică 'deadline', v.proto.
GraphQL: scheme, non-nule, directive, permisive la domenii.
Mesaje/fluxuri (Kafka/Pulsar/SQS): scheme de evenimente (Avro/JSON/Protobuf), chei de partiții, ordine, chei idempotente.
SDK-uri/Biblioteci interne: Caracteristici publice/Excepții/Contracte de performanță.

2) Modelul CDC: roluri și artefacte

Consumatorul publică contractul de așteptări (cereri de eșantion/răspunsuri, pariuri de tip, invarianți).
Furnizorul efectuează verificarea contractului împotriva service-ului/adaptorului/manipulatorilor săi.
Brokerul contractual (Pact Broker/Backstage/repo artefact) stochează versiuni, etichete ('prod',' staging ',' canary ') și' consumer @ v → provider @ v 'matrice de compatibilitate.
Politica de lansare: trimiterea unui furnizor este interzisă dacă este încălcat un contract „prod-relevant”.

3) Ce să se stabilească în contract (exemplu HTTP)

• Metodă/cale/parametri/anteturi (inclusiv Auth, cheie idempotentă).
• Caroserie și pariuri tipice (tip/format/regexp/intervale).
• Coduri de eroare și structură; stabil 'error _ code'.
• Invarianți semantici: sortare, unicitate, monotonie 'created _ at'.
• Așteptări nefuncționale (opționale): p95, limite de dimensiune, anteturi cu limită de rată.

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) Contracte bazate pe evenimente

Schema evenimentului: „tip”, „versiune”, „id',” a apărut _ at _ utc', „producător”, „subiect”, „sarcină utilă”.
Invarianți: invarianță "id' și idempotență prin" (tip, id) ", ordine în cheia piesei, monotonie" secvență ".
Schema Registry-Stochează evoluția și regulile de compatibilitate (înapoi/înainte/complet).
Testele contractelor de consum: reluarea evenimentelor și fazelor negative „de aur” (câmpuri necunoscute, nullable).

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) Evoluție și compatibilitate

Versiuni contractuale: semantica „MAJOR”. MINOR. PATCH "(MAJOR - rupere).

• Nu rupeți: nu ștergeți câmpurile, nu modificați tipul/valoarea „error _ code”.
• Adăugați câmpuri opționale cu implicit; noi puncte finale în loc de „magie”.
• Decret: declarație, suport concurent, ștergere prin valori.
• GraphQL: câmpuri add-only, non-null introduceți prin faze; decretarea directivelor.
• gRPC/Proto: nu reutilizați numerele de câmp; adăugați doar altele noi cu opțional.
• Evenimente: schema „vN”; consumatorii trebuie să ignore câmpurile necunoscute (clemență).

6) Controale negative și invariante

Negativ: tipuri incorecte, valori interzise, parametri conflictuali, depășirea limitelor.
Invarianți: sortarea răspunsurilor, unicitatea "id', corectitudinea" next _ cursor ", stabilitatea răspunsului idempotent atunci când este repetat.
Contracte de aspecte temporare: „creat _ at” RFC3339/UTC, proiecția corectă a zilelor locale nu face parte din contractul de transport - este prezentată invarianților de afaceri.

7) Generarea înjunghierii și dezvoltarea locală

Din contracte, stive de furnizori sunt generate pentru dezvoltarea consumatorilor.
Pentru evenimente - generatoare de mesaje „valide/borderline” conform schemei.
Personalul este marcat cu versiunea contractului și data construirii; publicarea în prod.

8) Încorporarea în CI/CD (conductă de referință)

1. IÎ de consum:

Lint/build → contract generation → unit/test contract → publicarea în contract-broker (tag: 'consumer @ 1. 7. 0`).

2. IÎ furnizor:

Ridicarea serviciului local/în container → preluarea contractelor relevante ("prod'/" stadializare") → verificarea → publicarea statutului în broker.

3. Poarta de eliberare:

Implementarea furnizorului este blocată dacă există contracte restante.

4. Matrice de noapte:

Matricea de compatibilitate „versiuni de consum × versiuni de furnizor”; rapoarte și alarme.

9) Exemple de practici pe domenii

9. 1 REST: paginare cursor (invariant contract)

Răspunsul conține 'items []', 'next _ cursor' (nullable), 'limit', 'total' (opțional).
Invarianți: „len (items) ≤ limit”, apel repetat cu același „cursor” → set idempotent.
Eroare dacă ambele sunt specificate 'cursor' și 'page'.

9. 2 POST idempotență

Contractul necesită antetul „Idempotency-Key”.
Invariant: O interogare repetată cu aceeași cheie returnează același "id'/stare.

9. 3 Evenimente: garanții de ordine

Cheia de partiție din contract este 'partition _ key = user_id'.
Invariant: „secvență” crește monotonic în cheie; consumatorul trebuie să se ocupe de reluări.

10) Securitatea și confidențialitatea în contracte

Nu includeți datele/secretele personale în exemple - numai sintetice.
Fixați anteturile de securitate obligatorii: „Autorizare”, „Semnătură X”, „Prevenire replay”.
Pentru webhooks - semnarea și contractul de răspuns „2xx ”/retroys.
În jurnalele testelor contractuale - mascarea câmpurilor sensibile.

11) Instrumente

Pact/Pactflow/Pact Broker - HTTP/Contracte de mesaje, matrice de compatibilitate.
OpenAPI/AsyncAPI - specificații + generatoare de testare (Dredd, Schemathesis).
Karate/REST Assured - controale de scenariu ale contractelor REST.
Protobuf/gRPC - „buf”, „protolint”, teste de compatibilitate; Schema Registry pentru Avro/JSON/Proto în fluxuri.
Teste de conformitate pentru GraphQL (graphql-compat), teste de circuit instantaneu.

12) Pseudocodul de verificare a furnizorului (simplificat)

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-modele

„Capturi de ecran Postman sunt un contract”: nu există versiuni/pariuri tipice/validare automată.
Overnapping: contractul stabilește valori exacte în loc de tipuri/modele → false cade.
Un contract comun pentru diferite regiuni/canale: ignoră variabilitatea (steaguri, geo-reguli).
Contracte fără broker/matrice: este imposibil de înțeles ce versiuni sunt compatibile.
Pariați pe e2e în loc de contracte: lent, scump, instabil.
Nu există cazuri negative/invariante: este testată doar „pista verde”.

14) Observabilitate și funcționare

Starea de export către broker + tabloul de bord „contracte de sănătate”.
Alerte: noi picături în furnizor împotriva contractelor "prod', o creștere a" câmpului necunoscut "în evenimente.
Trace: 'contract _ id',' version ',' decision _ id' în jurnalele de verificare.

15) Procesul de depresie

1. Se adaugă un câmp/punct final (fără rupere).
2. Marcați vechiul ca „depreciat” în caietul de sarcini, anunțați datele.
3. Urmăriți consumatorii prin jurnale/broker; ghiduri de migrare.
4. Activați „umbra” nega în scenă (uscat-run), apoi pune în aplicare.
5. Ștergeți după utilizarea și compatibilitatea zero.

16) Lista de verificare a arhitectului

1. Consumatorii și proprietarii lor identificate? Contractele sunt versionate?
2. Există un broker și o matrice de compatibilitate cu etichete de mediu?
3. Sunt incluse în contract negative și invariante (idiempotență, cursoare, sortare)?
4. Este Schema Registry și modul de compatibilitate configurat pentru evenimente?
5. Blocuri de conducte eliberarea furnizorului în cazul încălcării contractelor de producție?
6. Este descris procesul de depreciere și politica de evoluție?
7. Stabs sunt generate din contracte, există generatoare de evenimente locale?
8. Este documentată mascarea PD și rubricile obligatorii de siguranță?
9. Metrica/alerte privind contractele sunt conectate, există rapoarte derivă?
10. Contractele sunt revizuite în CI de ambele părți (consumator și furnizor)?

Concluzie

Testarea contractului transferă „adevărul” despre interacțiunile în artefacte versionate și face integrările previzibile. CDC, broker de contract și disciplina de evoluție a schemei înlocuiesc „spargerea surprizelor” cu un proces gestionat: verificări rapide, invarianți clari și compatibilitate transparentă a versiunii. Acest lucru reduce costul e2e, accelerează versiunile și îmbunătățește calitatea întregii platforme.