Protocol-first dizayni

Protocol-first nima

Protocol-first - bu komponentlar (servislar, mijozlar, tashqi sheriklar) o’rtasidagi o’zaro hamkorlik shartnomasi amalga oshirishdan oldin loyihalashtiriladigan va qayd etiladigan yondashuvdir. Kod, omborlar, infratuzilma va hujjatlar kontraktga bo’ysunadi va undan avtomatik ravishda hosil bo’ladi, aksincha emas.

API faqat qo’shimcha kod mahsuloti bo’lgan «code-first» dan farqli o’laroq, Protocol-first protokolni birlamchi artefaktga aylantiradi: u domen tushunchalari, ma’lumotlar modellari, statuslar, xatolar, idempotentlik semantikasi, SLO/SLI va hatto versiyalar siyosatiga ega.

Nima uchun kerak

Tashkilot miqyosida interfeyslarning muvofiqligi va bashorat qilinishi.
Tezkor onbording (SDK/stab/mijozlarning avtogeneratsiyasi, yagona xatolar va kodlar).
Ishonchli evolyutsiya (sxemalarning muvofiqligi, test-kontraktlar, aniq versiya siyosati).
Mahsulot fokusi: kodni yozishdan oldin xulq-atvorni, SLA va UX integratsiyasini muhokama qiling.
Avtomatlashtirish: CI/CD bitta haqiqat manbaidan artefaktlarni (mijozlar, server qulflari, validatorlar) yigʻadi.
Xavfsizlik va komplayens: huquqlar, PII niqobi, retensiya siyosati kontraktda mustahkamlangan.

Yondashuv yadrosi

1. Yagona haqiqat manbai (SSOT) - mashinada o’qiladigan spetsifikatsiyalar:

REST: OpenAPI/JSON Schema.
Voqealar va striming: AsyncAPI, Euro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + koʻrsatmalar/siyosatlar.
2. Amalga oshirishdan oldingi kelishuvlar: domen glossariysi, xato kodlari, idempotentlik semantikasi, muddatlar, retraylar, deduplikatsiya.
3. Avtogeneratsiya: mijozlar/server bloklari, turlari, SDK, kontrakt-testlar, moki, Postman-kolleksiyalari, Terraform/OpenAPI Gateway- .
4. Governance: linterlar/siyosatlar (naming, paginatsiya, filtrlar, xatolar), API gildiyasi orqali review, major versiyalar uchun change-advisory.
5. Muvofiqlik: «additive-only» difflarini qat’iy tekshirish, semantik versiyalash, canary/consumer-driven testlari.
6. Kontrakt darajasida kuzatilganlik: korrelyatsion ID, xato modellari, kechikish byudjetlari bayonnomada qayd etilgan.

Jarayon qanday (skelet)

1. Tashabbus: mahsulot brifi → user journeys → API/Protocol PRD (resurslar/usullar/voqealar, SLA/SLO, xatolar, limitlar).
2. Modellashtirish: tasvir loyihasi (OpenAPI/AsyncAPI/Proto) + maʼlumotlar sxemasi, atamalar lugʻati.
3. Shartnomalar va UX integratsiyasi: foydali yuk namunalari, xato kontraktlari, maqom xaritalari, versiyalash qoidalari.
4. Revyu va governance: linterlar/standartlar, domen invariantlarini muhokama qilish, lock-in MGC (minimal kafolat shartnomasi).
5. Artefaktlarning avtogeneratsiyasi: SDK, stab, test fiksturlari, infratuzilma tugmalari (Gateways, IAM scopes).
6. Amalga oshirish va kontrakt-testlar: yetkazib beruvchi va iste’molchilar CI da muvofiqlik tekshiruvidan o’tadilar.
7. Kuzatish va SLO: korrelation-id, error catalog bo’yicha trasovka, retraj/taymaut byudjetlari.
8. Relizlar va evolyutsiya: additive-first, deprecation policy, canary, A/B capability flags.

Protokollar va o’zaro hamkorlik uslublari

REST/HTTP

Standartlar: resurs modeli,’GET/POST/PATCH/DELETE’, paginatsiya (cursor), filtrlar, saralash.
Dala va sxemalar: JSON Schema, formatlar (’date-time’,’uid’), invariantlar (regex/enum/min-max).
Xatolar: yagona format (’type’,’code’,’title’,’detail’,’trace _ id’), HTTP sahifalarida mapping.
Oʻzgarishlarni nazorat qilish: ETag/If-Match, POST uchun idempotent kalitlar, 409/422 eksplitli semantiklar.

gRPC/RPC

Protobuf: tag’larning barqaror raqamlanishi,’optional’, cheklangan maydonlardan qayta foydalanishni taqiqlash.
Deadlines va kontraktdagi ustuvorliklar; barqaror maqomlar (OK, INVALID_ARGUMENT, FAILED_PRECONDITION va boshqalar).
Streaming: xabar tartibi, backpressure, yakuniy treylerlar.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: mavzular/kanallar, partiyalash kalitlari, deduplikatsiya, retensiya kalitlari to’g "risidagi bitimlar," to’g "ridan-to’g" ri bir marta "va" kamida bir marta "semantikasi.
Boyitish va boyitish tadbiri: minimal payload va kengaytirishni ajrating; ’event _ type ’/’ schema _ version’ versiyasi.
Idempotentlik:’event _ id’,’producer _ id’, retray va deduplikatsiya bo’yicha policy.

GraphQL

SDL kontrakt sifatida, deprekeyt uchun direktivalar, chuqurlik va murakkablik limitlari, xato kontrakti (error codes/extensions).

Arxitektura tamoyillari bilan integratsiya

Inverse Pyramid/Critical Path First: spetsifikatsiyada MGC (majburiy minimal), kengaytmalarni’? include = ’/capabilities orqali ajratish.
Paved Roads: tayyor spetsifikatsiya namunalari toʻplami (payment, KYC, audit, search, files) + linterlar.
API Gateways & Service Mesh: kontrakt asosidagi siyosatlar (rate-limits, auth scopes, retries, circuit-breakers).

Versionizatsiya va evolyutsiya

• Minor = faqat qoʻshimcha maydonlar/kanallar.
• Major = buzuvchi oʻzgarishlar (oʻchirish, nomini oʻzgartirish, semantikani oʻzgartirish).
• Deprecation Policy: qoʻllab-quvvatlash oynalari, «Sunset» sarlavhalari, xabarnoma hodisalari.
• Consumer-Driven Contracts (CDC): Joriy API aniq isteʼmolchilarni qanoatlantirishini tekshiryapmiz.
• Sxemalar katalogi: tarix va muvofiqlik qoidalariga ega reyestr (Schema Registry/Artifact Registry) (BACKWARD/FORWARD/FULL).

Xavfsizlik va komplayens

Autentifikatsiya/avtorizatsiya shartnomaning bir qismi sifatida (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: kamuflyaj, tokenizatsiya formatlari, maxsus saqlash rejimiga ega maydonlar/TTL.
Audit siyosati: majburiy atributlar (’actor’,’subject’,’action’,’occurred _ at’,’trace _ id’).
Limitlar: rate limit headers, kvotalar, xabarlar hajmi, muddatlar.

Kontrakt bo’yicha kuzatish

Correlation/Request-ID: spetsifikatsiyada majburiy.
Error Catalog: kodlar va SLAning oʻrnatilgan roʻyxati.
SLI/SLO: p50/p95 latency, muvaffaqiyatli javoblar ulushi, mos keladigan voqealar ulushi, idempotent takrorlar ulushi.

Test va sifat

Contract tests (isteʼmolchi yetkazib beruvchisi), CIdagi schema diff, mok-serverlar ishlab chiqarish.
Golden samples: soʻrovlar/javoblarning namunalari, e2e uchun fiksturlar.
Chaos/latency injection: taymaut/retraylarni tekshirish, MGC saqlanganda kengaytmalarni buzish.

Namunaviy domen namunalari

Toʻlov (REST + hodisalar)

’POST/payments’ (idempotent kaliti) →’201 Created’s’payment _ id’,’status = authorized’.
Payment. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
’payment’ ni kengaytirish. enriched. v1’: risk-skor, geo, device-fingerprint.
Xatolar:’422’(validatsiya),’402’(payment required),’409’(duplicate).
SLA: avtorizatsiya ≤ 800ms p95; yadro hodisasi ≤ 2s lag p95.

KYC (gRPC + navbatlar)

RPC `StartVerification(user_id)` → `operation_id`.
’kyc’ topikasidagi taraqqiyot voqealari. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Kontrakt PII-maydonlarni, saqlash muddatini, niqoblanishini, rad etishning sababiy kodlarini belgilaydi.

Audit (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Boyitish: IP, device, geo - alohida hodisa/oqim, yadrosini to’sib qo’ymaydi.

Asboblar va avtomatika (namunaviy stek)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Geytvey: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Reyestr: Git-sxemalar katalogi + Schema Registry/Artifact Registry.
Hujjatlar: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-patternlar

Code-first by accident: «avval MVP nazoratchilarda», post-faktum tavsifi, hujjatlar va xulq-atvor tafovutlari.
Swagger-wash: haqiqiy qoidalarsiz rasmiy OpenAPI (xatolar, limitlar, SLA, versiyalar).
Moslik buzilishi: maydon o’chirildi/major-versiyasiz turi o’zgartirildi; protobuf-teglardan qayta foydalanish.
Paginatsiyasiz/filtrsiz «Qalin» javob; idempotentlik yo’qligi.
Kontraktdan tashqari sekyuritlar: auth/Scopes vikida tasvirlangan, lekin spetsifikatsiyasida emas.

Jarayonni tashkil etish bilan o’zaro bog’liqlik

API Guild: standartlar homiylari, o’zgarishlar, o’qitish.
Design Docs: har bir API uchun - PRD, ADR (yechimlar), SLA, xavf matritsasi.
Change Management: RFC-jarayon, release notes, migratsiya gaydlari, deprecation-taymline.
Paved Road & Templates: Xizmat ramkalari generatorlari (xandlerlar skeleti, validatsiya, logirovka).

Chek varaqlari

Boshlashdan oldin

• PRD va domen soʻzlari mavjud.
• Sxemalar uslubi (REST/gRPC/Event/GraphQL) va formati tanlangan.
• MGC, xatolar, SLA/SLO, idempotentlik qoidalari aniqlangan.

Ishlab chiqishda

• Spetsifikatsiya linterlar va review orqali o’tadi.
• SDK/stab/fikstur avtogeneratsiyasi sozlandi.
• Kontrakt-testlar (CDC) CIga kiritilgan; schema-diff mos kelmaydigan oʻzgarishlarni bloklaydi.

Chiqarishdan oldin

• Misollar va xato kodlari bilan integratorlar uchun hujjatlar.
• Kontrakt bo’yicha kuzatish darajasi: correlation-id, error catalog, SLI dashbordlari.
• Version va deprecation siyosati e’lon qilindi.

FAQ

Protocol-first API-first dan qanday farq qiladi?
Ko’pincha atamalar sinonim sifatida ishlatiladi. Ushbu maqolada Protocol-first ostida biz shartnomaning qattiqligini va barcha uslublar (REST/RPC/Events/GraphQL), shu jumladan SLA, xavfsizlik va kuzatuv darajasini ta’kidlaymiz.

Bu ishlanmani sekinlashtiradimi?
Ishga tushirish biroz uzoqroq bo’lishi mumkin, ammo keyin integratsiya, barqarorlik va parallel ishlab chiqish tezligida (avtogeneratsiya, barqaror SDK) g’alaba qozonamiz.

Tezkor tajribalar bilan nima qilish kerak?
Sxemalarning (draft), feature flags va qum qutilarining «qoralama» versiyalaridan foydalaning, lekin linterlar va moslashuv qoidalarini oʻtkazib yubormang.

Jami

Protocol-first dizayn shartnomani arxitektura markazi qiladi: xulq-atvorni muvofiqlashtirish, sxemalarni tuzatish, ishlab chiqarish va testlarni avtomatlashtirish, qo’shimcha evolyutsiya. Natijada biz oldindan aytib boʻladigan integratsiyalashuvlarni, yuqori rivojlanish tezligini va tizim va jamoa miqyosidagi oʻzgarishlarga chidamliligini olamiz.