Kontrakt sinovi

1) Kontraktlarni qayerda qo’llash kerak

HTTP REST/JSON: resurslar, paginatsiya, filtrlar, idempotentlik, xato kodlari.
gRPC/Protobuf: xabar turlari, statuslar, semantika’deadline’, backward-compat v.proto.
GraphQL: sxemalar, non-null, direktivalar, permishenlar.
Xabarlar/oqimlar (Kafka/Pulsar/SQS): event-sxemalar (Euro/JSON/Protobuf), partiyalash kalitlari, tartib, idempotent kalitlari.
Ichki SDK/kutubxonalar: ommaviy funksiyalar/istisnolar/unumdorlik shartnomalari.

2) CDC modeli: rollar va artefaktlar

Iste’molchi kutish kontraktini (taxminiy so’rovlar/javoblar, turdagi matchyerlar, invariantlar) e’lon qiladi.
Etkazib beruvchi o’z servisi/adapteriga/handlerlariga qarshi kontraktlarni tekshirishni amalga oshiradi.
Kontraktlar brokeri (Pact Broker/Backstage/artefakt-repo) versiyalarni, teglarni (’prod’,’staging’,’canary’) va matritsani’consumer @v → provider @v’saqlaydi.
Reliz siyosati: agar har qanday «prod-relevant» kontrakt buzilgan bo’lsa, provayder deplasi tomonidan taqiqlangan.

3) Kontraktda nimani qayd etish kerak (HTTP misol)

• Usul/yoʻl/parametrlar/sarlavhalar (jumladan, auth, idempotent kaliti).
• Tana va tipdagi matchyerlar (turi/formati/regeksp/diapazonlari).
• Xato kodlari va tuzilmasi; barqaror’error _ code’.
• Semantik invariantlar: saralash, noyoblik, monotonlik’created _ at’.
• Funktsional bo’lmagan kutishlar (ixtiyoriy): p95, o’lcham limitlari, rate-limit sarlavhalari.

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) Voqealar uchun kontraktlar (event-driven)

Hodisa sxemasi:’type’,’version’,’id’,’occurred _ at _ utc’,’producer’,’subject’,’payload’.
Invariantlar:’id’ning o’zgarmasligi va’(type, id)’bo’yicha idempotentlik, partiya kaliti doirasidagi tartib,’sequence’ning monotonligi.
Schema Registry: evolyutsiya va muvofiqlik qoidalarini saqlaydi (backward/forward/full).
Konsumer kontrakt-testlari: «oltin» voqealar va salbiy fazalar (noma’lum maydonlar, nullable) takrorlanadi.

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) Evolyutsiya va muvofiqlik

Kontraktlar versiyasi: MAJOR semantikasi. MINOR. PATCH’(MAJOR - buzuvchi).

• Maydonlarni olib tashlamang,’error _ code’turini/qiymatini oʻzgartirmang.
• Variant maydonlarini defolt bilan qoʻshing; «sehr» o’rniga yangi endpointlar.
• Depreksiya: e’lon, parallel qo’llab-quvvatlash, metriklar bo’yicha olib tashlash.
• GraphQL: faz orqali faqat qoʻshish, non-null kiritish; deprekatsiya direktivalari.
• gRPC/Proto: maydon raqamlarini qayta ishlatmaslik; Faqat optional bilan yangilarini qoʻshish.
• Events:’vN’sxemasi; konsumerlar noma’lum maydonlarni (leniyentlik) e’tiborsiz qoldirishlari shart.

6) Salbiy va invariant tekshiruvlar

Negative: notoʻgʻri turlar, taqiqlangan qiymatlar, ziddiyatli parametrlar, chegaralardan oshib ketish.
Invariants: javoblarni saralash,’id’ning oʻziga xosligi,’next _ cursor’ning toʻgʻriligi, takrorlashda idempotent javobning barqarorligi.
Vaqtinchalik jihatlar kontraktlari:’created _ at’RFC3339/UTC, mahalliy sutkaning to’g "ri proyeksiyasi transport kontraktining bir qismi hisoblanmaydi - biznes-invariantlarga kiritiladi.

7) Stab-generatsiya va lokal ishlab chiqish

Kontraktlardan iste’molchini ishlab chiqish uchun provayder stablari ishlab chiqiladi.
Hodisalar uchun - sxema bo’yicha «valid/chegara» xabarlari generatorlari.
Bloklar kontrakt versiyasi va yig’ilish sanasi bilan belgilanadi; prodda e’lon qilish taqiqlangan.

8) CI/CD (referens-paypline) ga joylashtirish

1. Consumer CI:

Lint/yig’ish → shartnomalar yaratish → yunit/kontrakt-testlar → contract-broker (tag:’consumer @ 1. 7. 0`).

2. Provider CI:

Servisni mahalliy/konteynerda ko’tarish → relevant kontraktlar fetch (’prod ’/’ staging’) → verifikatsiya → maqomini brokerda e’lon qilish.

3. Release Gate:

Agar bajarilmagan shartnomalar mavjud bo’lsa, provayder deplasi tomonidan bloklanadi.

4. Nightly Matrix:

Matrix mosligi’consumer versions × provider versions’; hisobotlar va tashvishlar.

9) Domenlar bo’yicha amaliyot namunalari

9. 1 REST: kursorlar tomonidan paginatsiya (kontrakt invarianti)

Javobda’items []’,’next _ cursor’(nullable),’limit’,’total’(ixtiyoriy) mavjud.
Invariantlar:’len (items) ≤ limit’, bir xil’cursor’→ idempotent toʻplami bilan qayta chaqirish.
’cursor’ va’page’bir vaqtning oʻzida oʻrnatilgan boʻlsa xato roʻy berdi.

9. 2 POST idempotentligi

Shartnoma «Idempotency-Key» sarlavhasini talab qiladi.
Invariant: xuddi shu’id ’/maqom bilan qayta soʻrash.

9. 3 Voqealar: tartib kafolatlari

Kontraktdagi partiyalashtirish kaliti:’partition _ key = user_id'.
Invariant:’sequence’kalitning ichida monoton ravishda o’sadi; konsumer takrorlarni qayta ishlashi shart.

10) Kontraktlardagi xavfsizlik va maxfiylik

PD/sirlarni misollarga kiritmaslik - faqat sintetika.
«Authorization», «X-Signature», «Replay-Prevention» kabi majburiy xavfsizlik sarlavhalarini belgilash.
Vebxuklar uchun - imzo va javob kontrakti’2xx ’/retray.
Test-kontrakt daftarlarida - sezgir maydonlarni yashirish.

11) Asboblar

Pact/Pactflow/Pact Broker - HTTP/Message shartnomalari, moslik matritsasi.
OpenAPI/AsyncAPI - spetsifikatsiyalar + test generatorlari (Dredd, Schemathesis).
Karate/REST Assured - REST kontraktlarini ssenariy asosida tekshirish.
Protobuf/gRPC -’buf’,’protolint’, muvofiqlik testlari; Euro/JSON/Proto uchun Schema Registry.
GraphQL (graphql-compat) uchun Conformance testlari, sxemalarning snapshot testlari.

12) Provayderni tekshirish soxta hujjati (soddalashtirilgan holda)

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

«Postman skrinshotlari - bu kontrakt»: versiyalar/tipik matchyerlar/avtomatik validatsiya yo’q.
Oversneyping: kontrakt turlar/patternlar o’rniga aniq qiymatlarni belgilaydi → soxta tushishlar.
Turli mintaqalar/kanallar uchun bitta umumiy kontrakt: o’zgaruvchanlikni e’tiborsiz qoldiradi (bayroqlar, geo-qoidalar).
Broker/matritsasiz shartnomalar: qaysi versiyalar mos kelishini tushunish mumkin emas.
Kontraktlar o’rniga e2e stavkasi: sekin, qimmat, beqaror.
Salbiy/invariant holatlarning yo’qligi: faqat «yashil yo’l» sinovdan o’tkaziladi.

14) Kuzatish va foydalanish

Broker + dashbord «health kontraktlar» maqomini eksport qilish.
Alertlar: provayderning’prod’shartnomalariga qarshi yangi qulashi, voqealarda «unknown field» ning o’sishi.
Trastirovka:’contract _ id’,’version’,’decision _ id’.

15) Deprekatsiya jarayoni

1. Maydon/endpoint qoʻshish (buzilmaydi).
2. Eskisini spetsifikatsiyada «deprecated» deb belgilash, muddatlarni eʼlon qilish.
3. Log/broker orqali iste’molchilarni kuzatish; migratsiya gaydalari.
4. Steyjda «soyali» deny (dry-run) ni yoqish, keyin enforce.
5. Foydalanishning nol qismi va muvofiqligi tasdiqlangandan keyin olib tashlash.

16) Arxitektorning chek-varaqasi

1. Isteʼmolchilar va ularning egalari aniqlanganmi? Shartnomalar versiyalanadimi?
2. Broker va muhit belgilari matritsasi bormi?
3. Kontraktga salbiy va invariantlar (idiempotentlik, kursorlar, saralash) kiritilganmi?
4. Hodisalar uchun Schema Registry va moslashuv moslamasi oʻrnatilganmi?
5. Paypline prod-kontraktlar buzilganda provayderning chiqarilishini bloklaydimi?
6. Deprekatsiya jarayoni va evolyutsiya siyosati tasvirlanganmi?
7. Shartnomalar bo’yicha bloklar yaratilyaptimi, voqealarning mahalliy generatorlari bormi?
8. PD niqobi va majburiy xavfsizlik sarlavhalari hujjatlashtirilganmi?
9. Kontraktlar bo’yicha metriklar/alertlar ulangan, drift bo’yicha hisobotlar bormi?
10. Shartnomalar CIda ikkala tomonda ham (consumer va provider) tekshiriladimi?

Xulosa

Kontrakt test sinovi o’zaro ta’sir to’g’risidagi «haqiqatni» versiyalashtiriladigan artefaktlarga o’tkazadi va integratsiyani oldindan aytib bo’lmaydigan qiladi. CDC, kontraktlar brokeri va sxemalar evolyutsiyasi intizomi «buzuvchi kutilmagan hodisalar» o’rnini boshqariladigan jarayonga almashtiradi: tezkor tekshiruvlar, aniq invariantlar va versiyalarning shaffof muvofiqligi. Bu e2e narxini pasaytiradi, relizlarni tezlashtiradi va butun platforma sifatini yaxshilaydi.