API kontrakt sinovi

1) Nima uchun kontrakt bo’yicha test

Kontrakt mijozning umidlari va provayderning va’dalarini qayd etadi: yo’nalishlar/usullar, sarlavhalar, jismlar sxemalari, maqomlar, xatolar semantikasi va cheklovlar. Maqsad - integratsiyalashishdan oldin nomuvofiq o’zgarishlarni ushlash va xavfsiz, og’ir E2E chiqarishdan iborat.

2) yondashuvlar

Consumer-Driven Contracts (CDC): mijoz kutilmalarni shakllantiradi (Pact va analoglar); provayder ularni muntazam ravishda tekshirib turadi.
Spetsifikatsion: yagona haqiqat manbai sifatida kontrakt (OpenAPI/Protobuf/GraphQL SDL); testlar spetsifikatsiyaga qarshi amalga oshirilishini tasdiqlaydi.
Hodisa: xabarlar sxemasi (Euro/JSON Schema/Protobuf) + broker/reyestrdagi muvofiqlik qoidalari.

3) HTTP/REST: spetsifikatsion oqim

1. Kontrakt: OpenAPI 3. x (sxemalar, misollar, kodlar).
2. Lint va statistik tahlil: uslub, majburiy maydonlar, yagona kodlar.
3. Amalga oshirishni validatsiya qilish: OpenAPI (schemathesis/Dredd-yondashuv) ga qarshi test generatorlari + qo’l negativlari.
4. Snapshotlar: javoblar namunalarini, ETag semantikasini, idempotentlik sarlavhalarini yozib oling.

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-yondashuv)

1. Consumer testni yozadi, pact faylini shakllantiradi (kutish).

2. Brokerga (artefaktga) e’lon qilish.

3. Provider CI’da xizmatni (yoki kontrakt-stoykani) ko’taradi, pact’larni tekshiradi.

4. Broker can-i-deploy muvofiqlik matritsasini hisoblab chiqadi.

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 kontraktlari

Kontrakt -’.proto’s versionirovaniya paketov/servisov.
Moslik: teglarni qayta ishlatmaslik, faqat optional bilan yangilarini qoʻshish, ishlatiladigan maydonlarni oʻchirmaslik; raqamlarni zaxiralash.
Testlar: server/mijoz stabini yaratish, avtoulov ishlab chiqarilgan keyslarni ijaraga berish + negativlar (unknown fields, size-limits).

6) Hodisa shartnomalari (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Muvofiqlik siyosati:’BACKWARD’yoki’FULL’.
Prodyuser testlari: xabarni sxemaga qarshi validatsiya qiladi; konsumer testlari: eski va yangi versiyani qabul qiladi.
Invariantlar: idempotentlik kalitlari, tartib/takrorlanuvchanlik, deduplikatsiya semantikasi.

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

7) Muvofiqlik va versiyalar

Backward-compatible (tavsiya etilgan minimal): ixtiyoriy maydonlarni qoʻshing, mavjud maydonlarni buzmang.
Forward-compatible: isteʼmolchilar nomaʼlum maydonlarga eʼtibor bermaydi.
Full: ikkalasi ham.
Version:’path (/v1)’,’Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-siyosat: chiqish oynasi (masalan, 90 kun), ogohlantiruvchi sarlavhalar/voqealar.

8) Salbiy va xatolar - bu ham kontrakt

Kodlarni standartlashtiring: 400/401/403/404/409/422/429/5xx, majburiy’code’,’message’,’trace _ id’.
Miqdorlar/limitlar - kontraktning bir qismi (413/414/431).
Idempotentlik: takrorlanishdagi xatti-harakatlar (409 vs 201 same id).
Sarlavhalar: 429/503 da’Retry-After’,’Idempotency-Key’,’Content-Language’va h.k.

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

9) Ma’lumotlarni kontrakt boshqaradi

Misollar/namunaviy javoblar (examples) - tirik, CI da tasdiqlanadi.
CDC uchun fiksturlar - minimal, aniqlangan.
Ma’lumotlar generatsiyasi - sonlar/sanalar uchun property-based; lekin snapshotlarning barqarorligini buzmaslik.

10) CI/CD dagi Paypline (referens)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: kontrakt artefakt sifatida (broker/reyestr).
3. Verify: provayder CDC paketlarini/spetsifikatsiya testlarini haydab chiqaradi.
4. can-i-deploy gate: yashil matritsasiz chiqarish taqiqlanadi.
5. Diff: oʻzgarishlar mos kelishini tekshirish (semantic diff).
6. Hisobot: JUnit/HTML, qoidabuzarliklar/definitsiyalar ro’yxati.

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) Asboblar (vazifalar klasslari bo’yicha)

Lint/validatorlar: openapi-linters, protobuf-lint, euro-tools.
CDC: Pact oilasi/broker, Spring Cloud Contract, Hoverfly (HTTP yozuvlari/repleylari).
Spetsifikatsion rannerlar: schemathesis/Dredd-shunga o’xshash yondashuv, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Euro (breaking-oʻzgarishlarni aniqlaydi).
Konteynerlar: Testcontainers provayderni/kontraktlarni ko’tarish uchun.

12) Antipatternlar

«Spetsdok» koddan alohida → rassinxronizatsiya. Shartnomani xizmat yonida saqlang.
Kontrakt o’rniga tashqi servis moki → yangilanishlarda mo’rt.
Tasodifiy javoblar/sxemaga bogʻlanmagan generatsiya → fleyka.
Varianti boʻlmagan maydonlarning turi/majburiyligini oʻzgartirish.
Ogohlantirishsiz/deprekatsiyasiz silent-kengaytmalar.
Salbiy kontraktlar va xato kodlarining yo’qligi.

13) iGaming/Moliya xususiyatlari

Pul maydonlarini rasmiylashtiring:’amount’- masshtabli decimal, valyuta - ISO-4217, summalarning invariantlari.
To’lov/vebxuk kontraktlari: HMAC/mTLS, anti-replay (’X-Timestamp’oyna), idempotentlik,’Retry-After’.
Hududiylik/tenantlar: «X-Tenant/X-Region» sarlavhalari, xabarlarni mahalliylashtirish.
Voqealar: oʻzgarmas jurnallar (audit), deduplikatsiya kalitlari, yetkazib berish kafolatlari (at least once + idempotent xendlerlar).

14) Testlarning «skeletlari» misollari

14. 1 Schemathesis-stil (psevdo)

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

14. 2 Postman spetsifikatsion ranner sifatida

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

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

15) Prod-tayyorlik chek-varaqasi

• Repozitoriyadagi shartnomalar, CI artefaktlarni tasdiqlaydi va nashr etadi.
• CDC tanqidiy integratsiyalar uchun kiritilgan; broker/matrix «can-i-deploy» ishlaydi.
• Muvofiqlik siyosati (HTTP/gRPC/Events) hujjatlashtirilgan; avtomatik semantic-diff.
• Salbiy kontraktlar: xatolar, o’lchov limitlari, idempotentlik,’Retry-After’.
• Test-ma’lumotlar aniqlangan; misollar qo’llab-quvvatlanadi.
• Versiyalash va deprecation: muddatlar, xabarnomalar, sarlavhalar.
• Voqealar uchun - Schema Registry va muvofiqlik rejimi; prodyuser/konsumer ikkala versiyani ham sinovdan o’tkazadi.
• Artefaktlar: JUnit/HTML, diff/verify hisobotlari, moslik matritsasi.
• Hodisa-protsedura: tezkor kontrakt rollback/ficha-bayroq, integratorlarni xabardor qilish.

16) TL; DR

Shartnomalardagi umidlarni yozib oling va ularni avtomatik ravishda haydab chiqaring: mijoz umidlari uchun CDC, amalga oshirish uchun spetsifikatsiya testlari, voqealar uchun sxemalar reyestri. Qat’iy muvofiqlik siyosatini va salbiy kontraktlarni (xatolar, limitlar, idempotentlik) saqlang. Yashil can-i-deploy matritsasiz va semantic-diffni breaking-oʻzgarishlarsiz chiqarib boʻlmaydi.