Testarea contractului API

1) De ce testarea contractelor

Contractul surprinde așteptările clienților și promite furnizorul: rute/metode, antete, scheme corporale, stări, semantici de eroare și constrângeri. Scopul este de a prinde modificări incompatibile înainte de integrare și versiuni de presă în condiții de siguranță, fără E2E grele.

2) Abordări

Contracte bazate pe consumatori (CDC): clientul formează așteptări (pact și analogi); furnizorul le verifică în mod regulat.
Caietul de sarcini: contract ca o singură sursă de adevăr (OpenAPI/Protobuf/GraphQL SDL); testele validează implementarea împotriva specificațiilor.
Bazat pe evenimente: scheme de mesaje (Avro/JSON Schema/Protobuf) + reguli de compatibilitate broker/registru.

3) fluxul de specificații HTTP/REST

1. Contract: OpenAPI 3. x (diagrame, exemple, coduri).
2. Analiza Lint și stat: stil, câmpuri obligatorii, coduri uniforme.
3. Validarea implementării: generator de testare anti-OpenAPI (schemă/abordare Dredd) + negative manuale.
4. Instantanee: capturați răspunsurile eșantionului, semantica ETag, anteturile idempotenței.

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 (abordarea pactului)

1. Consumatorul scrie un test, generează un fișier pact (așteptări).

2. Publicarea într-un broker (artefact).

3. Furnizorul în CI ridică serviciul (sau contractul-rack), verifică pactul.

4. Brokerul calculează matricea de compatibilitate can-i-implementa.

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) contracte gRPC/Protobuf

Contractul este '.proto' cu versionarea pachetelor/serviciilor.
Compatibilitate: nu reutilizați etichetele, adăugați doar altele noi cu opțional, nu ștergeți câmpurile utilizate; numere de rezervă.
Teste: generarea de înjunghieri server/client, închirierea de cazuri generate automat + negative (câmpuri necunoscute, limite de dimensiuni).

6) Contracte de evenimente (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Politica de compatibilitate este 'BACKWARD' (destul de des) sau 'FULL'.
Testele producătorilor: validează mesajul împotriva schemei; teste de consum: acceptă versiuni vechi și noi.
Invarianți: chei de idempotență, ordine/repetabilitate, semantică de eliminare a duplicatelor.

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

7) Compatibilitate și versiuni

Compatibil înapoi (minim recomandat): adăugați câmpuri opționale, nu le rupeți pe cele existente.
Compatibil înainte: Consumatorii ignoră câmpurile necunoscute.
Full: Ambele.
Versioning: 'path (/v1)', 'Accept: application/vnd. brand. v2 + json ',' proto pachet v2 '.
Politica de abatere: fereastră de ieșire (de exemplu, 90 de zile), anteturi/evenimente de avertizare.

8) Negativ și greșeli sunt, de asemenea, un contract

Standardizarea codurilor: 400/401/403/404/409/422/429/5xx, câmpuri obligatorii "cod", "mesaj", "trace _ id'.
Dimensiunile/limitele fac parte din contract (413/414/431).
Idempotență: comportament de repetiție (409 vs 201 același id).
Rubrici: „Retry-After” la 429/503, „Idempotency-Key”, „Content-Language” etc.

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

9) Date gestionate prin contract

Exemple - live, validat în CI.
Corpurile pentru CDC sunt minime, deterministe.
Generarea de date - bazate pe proprietăți pentru numere/date; dar nu pentru a rupe stabilitatea instantaneelor.

10) Conducte în CI/CD (referință)

1. Lint/validate: OpenAPI/Proto/Avro ('validate', style- линер).
2. Publicare: Contract ca artefact (broker/registru).
3. Verificați: furnizorul rulează pachete CDC/teste de specificații.
4. can-i-disploy gate: nu este permisă eliberarea fără matrice verde.
5. Diff-Verifică faptul că schimbările sunt diff semantice.
6. Raport: JUnit/HTML, lista de încălcări/definiții.

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) Instrumente (pe clase de sarcini)

Lint/validatoare: openapi-lintere, protobuf-scame, avro-unelte.
CDC: Pact familie/broker, Spring Cloud Contract, Hoverfly (HTTP înregistrări/reluări).
Caietul de sarcini alergători: schemathesis/Dredd-like approach, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (detectează modificări de rupere).
Containere: Testcontainere pentru a ridica furnizor/birou de contract.

12) Antipattern

„Doc special” separat de codul → desincronizare. Ţine contractul lângă serviciu.
Moki unui serviciu terț în loc de un contract → fragilitate în timpul actualizărilor.
Răspunsuri aleatorii/generare fără legare la schema de fulgi de →.
Schimbarea tipurilor/câmpurilor obligatorii fără versiune.
Extensii silențioase fără notificare/decretare.
Nu există contracte negative și coduri de eroare.

13) Specificul iGaming/Finanțe

Formalizați câmpurile monetare: „sumă” - zecimală cu scară, monedă - ISO-4217, invarianți de sume.
Contracte de plată/webhook: HMAC/mTLS, anti-reluare (fereastra „X-Timestamp”), idempotență, „Retry-After”.
Regionalitate/chiriași: anteturile obligatorii „X-Tenant/X-Region”, localizarea mesajelor.
Evenimente: jurnale neschimbate (audit), chei de eliminare a duplicatelor, garanții de livrare (cel puțin o dată + manipulatori idempotenți).

14) Exemple de „schelete” de teste

14. 1 Schema-stil (pseudo)

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

14. 2 Poștașul ca alergător de specificații

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 Verificarea furnizorului CDC (Pseudo)

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

15) Lista de verificare Prod Readiness

• Contracte în depozit, CI validează și publică artefacte.
• CDC activat pentru integrări critice; broker/matrice „can-i-implementare” lucrări.
• Politica de compatibilitate (HTTP/gRPC/Events) documentată; semantic-diff automat.
• Contracte negative: erori, limite de dimensiune, idempotence, 'Retry-After'.
• Datele de testare sunt deterministe; instantanee de exemple sunt acceptate.
• Versionare și depreciere: termene limită, notificări, antete.
• Pentru evenimente - Schema Registry și modul de compatibilitate; Producătorul/consumatorul testează ambele versiuni.
• Artefacte: JUnit/HTML, diff/verifica rapoarte, matrice de compatibilitate.
• Procedura incident: contract rapid rollback/caracteristică de pavilion, notificarea integratorilor.

16) TL; DR

Capturați așteptările în contracte și rulați-le automat: CDC pentru așteptările clienților, teste de specificații pentru a se potrivi implementării, registru schemă pentru evenimente. Păstrați politici stricte de compatibilitate și contracte negative (erori, limite, idempotență). Nu puteți elibera fără o matrice verde can-i-implementa și semantic-diff fără modificări de rupere.