API müqavilə testi

1) Niyə müqavilə testi

Müqavilə müştərinin gözləntilərini və provayderin vədlərini qeyd edir: marşrutlar/metodlar, başlıqlar, cisimlərin sxemləri, statuslar, səhvlərin semantikası və məhdudiyyətlər. Məqsəd inteqrasiyadan əvvəl uyğunsuz dəyişiklikləri tutmaq və versiyaları təhlükəsiz, ağır E2E olmadan buraxmaqdır.

2) Yanaşmalar

Consumer-Driven Contracts (CDC): müştəri gözləntiləri formalaşdırır (Pact və analoqları); provayder mütəmadi olaraq onları yoxlayır.
Spesifikasiya: müqavilə vahid həqiqət mənbəyi kimi (OpenAPI/Protobuf/GraphQL SDL); testlər spesifikasiyaya qarşı həyata keçirilməsini təsdiqləyir.
Hadisə: mesaj sxemləri (Avro/JSON Schema/Protobuf) + broker/reyestr uyğunluq qaydaları.

3) HTTP/REST: spesifikasiya axını

1. Müqavilə: OpenAPI 3. x (sxemlər, nümunələr, kodlar).
2. Lint və statistik analiz: stil, məcburi sahələr, vahid kodlar.
3. Tətbiq validasiya: OpenAPI-yə qarşı test generatoru (schemathesis/Dredd-yanaşma) + əl neqativləri.
4. Snapshotlar: cavab nümunələrini, ETag semantikasını, idempotentlik başlıqlarını qeyd edin.

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-yanaşma)

1. Consumer test yazır, pact fayl (gözləntilər) formalaşdırır.

2. Broker nəşr (artefakt).

3. CI Provider xidməti (və ya raf müqaviləsi) qaldırır, pact-ları yoxlayır.

4. Broker can-i-deploy uyğunluq matrisi hesablayır.

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 müqavilələri

Müqavilə - paketlərin/xidmətlərin versiyası ilə '.proto'.
Uyğunluq: etiketləri yenidən istifadə etməyin, yalnız optional ilə yenisini əlavə edin, istifadə olunan sahələri silməyin; nömrələri sifariş.
Testlər: server/müştəri stabinin generasiyası, avtomatik yaradılan halların icarəsi + neqativlər (unknown fields, size-limits).

6) Hadisə müqavilələri (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Uyğunluq siyasəti: 'BACKWARD' (çox vaxt kifayətdir) və ya 'FULL'.
Prodüser testləri: sxemə qarşı mesajı təsdiqləyir; konsumer testləri: köhnə və yeni versiyasını qəbul edir.
İnvariantlar: idempotentlik açarları, ardıcıllıq/təkrarlanabilirlik, deduplikasiya semantikası.

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

7) Uyğunluq və versiyası

Backward-compatible (tövsiyə olunan minimum): Əlavə sahələr əlavə edin, mövcud sahələri sındırmayın.
Forward-compatible: istehlakçılar naməlum sahələrə məhəl qoymur.
Full: hər ikisi.
Versiyası: 'path (/v1)', 'Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-siyasət: çıxış pəncərəsi (məsələn, 90 gün), xəbərdarlıq başlıqları/hadisələr.

8) Mənfi və səhvlər də müqavilədir

Kodları standartlaşdırın: 400/401/403/404/409/422/429/5xx, məcburi 'code', 'message', 'trace _ id'.
Ölçülər/limitlər - müqavilənin bir hissəsi (413/414/431).
İdempotentlik: təkrarlanan davranış (409 vs 201 same id).
Başlıqlar: 429/503-də 'Retry-After', 'Idempotency-Key', 'Content-Language' və s.

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

9) Məlumatlar müqavilə ilə idarə olunur

Nümunələr/soyunma cavabları (examples) - canlı, CI-də təsdiqlənir.
CDC üçün fiksturlar - minimal, determinant.
Data Generation - ədədlər/tarixlər üçün property-based; lakin snapshot sabitliyini pozmayın.

10) CI/CD-də Paypline (istinad)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: artefakt kimi müqavilə (broker/reyestr).
3. Verify: provayder CDC paketlərini/spesifikasiya testlərini qaçırır.
4. can-i-deploy gate: yaşıl matrissiz buraxılış qadağandır.
5. Diff: dəyişikliklərin uyğun olduğunu yoxlamaq (semantic diff).
6. Report: JUnit/HTML, pozuntuların/definitsiyaların siyahısı.

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) Alətlər (tapşırıq siniflərinə görə)

Lint/validatorlar: openapi-linters, protobuf-lint, avro-tools.
CDC: Pact-ailə/broker, Spring Cloud Contract, Hoverfly (HTTP qeydləri/replay).
Spesifikasiya rannerləri: schemathesis/Dredd oxşar yanaşma, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (breaking-dəyişikliklər aşkar).
Konteynerlər: Provayder/Rack müqavilələri qaldırmaq üçün Testcontainers.

12) Antipattern

«Xüsusi dok» koddan ayrı → rasinxronizasiya. Müqaviləni xidmətin yanında saxlayın.
Müqavilə əvəzinə üçüncü tərəf xidmət moki → yeniləmələrdə kövrəklik.
Təsadüfi cavablar/→ fleyka sxeminə bağlanmadan generasiya.
Versiyasız sahələrin növlərini/məcburiyyətini dəyişdirin.
Silent-uzantıları bildiriş/depreqasiya olmadan.
Mənfi müqavilələrin və səhv kodlarının olmaması.

13) iGaming/Maliyyə Xüsusiyyətləri

Pul sahələrini rəsmiləşdirin: 'amount' - ölçülü decimal, valyuta - ISO-4217, məbləğlərin invariantları.
Ödəniş/vebhuk müqavilələri: HMAC/mTLS, anti-replay ('X-Timestamp' pəncərə), idempotentlik, 'Retry-After'.
Regionallıq/tenantlar: məcburi başlıqlar 'X-Tenant/X-Region', mesajların lokallaşdırılması.
Hadisələr: dəyişməz jurnallar (audit), deduplikasiya açarları, çatdırılma zəmanətləri (at least once + idempotent hendlerlər).

14) Testlərin «skelet» nümunələri

14. 1 Schemathesis-stil (psevdo)

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

14. 2 Postman spesifikasiya ranner kimi

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-yoxlama (psevdo)

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

15) Prod hazırlıq yoxlama siyahısı

• Resepsiyondakı müqavilələr, CI əsərləri təsdiqləyir və dərc edir.
• CDC kritik inteqrasiya üçün daxil; broker/matrix «can-i-deploy» işləyir.
• Uyğunluq siyasəti (HTTP/gRPC/Events) sənədləşdirilmişdir; avtomatik semantic-diff.
• Mənfi müqavilələr: səhvlər, ölçü limitləri, idempotentlik, 'Retry-After'.
• Test-data determined; nümunələrin snapshot dəstəklənir.
• Version və deprecation: vaxt, bildirişlər, başlıqlar.
• Hadisələr üçün - Schema Registry və uyğunluq rejimi; prodüser/konsumer hər iki versiyanı sınaqdan keçirir.
• Artefaktlar: JUnit/HTML, diff/verify hesabatları, uyğunluq matrisi.
• Hadisə proseduru: sürətli rollback müqaviləsi/Ficha bayrağı, inteqratorlara bildiriş.

16) TL; DR

Müqavilələrdə gözləntiləri qeyd edin və onları avtomatik olaraq qaçırın: müştəri gözləntiləri üçün CDC, həyata keçirilməsi üçün spesifikasiya testləri, hadisələr üçün sxemlərin reyestri. Ciddi uyğunluq siyasəti və mənfi müqavilələr (səhvlər, limitlər, idempotentlik) saxlayın. Yaşıl can-i-deploy matrisi və semantic-diff olmadan breaking-dəyişikliklər olmadan buraxıla bilməz.