Referens-implementatsiyalar

1) Maqsadlar, chegaralar va prinsiplar

1. Bayonnoma/izohni aniq talqin qilish.

2. Muvofiqlikni mustaqil tekshirishni ta’minlash.

3. Mijoz/server/vebxuklarning ish namunalarini taqdim etish.

4. Integratsiya va joriy etish qiymatini pasaytirish.

• RI maksimal unumdorlikka emas, balki xulq-atvorga e’tibor qaratadi.
• Prod-sozlamalarning minimal to’plamini o’z ichiga oladi (TLS, loging, metrika, treysing, limiterlar).
• Tijorat/mahsulot sotish o’rnini bosmaydi, lekin «pastki sifat plankasi» ni belgilaydi.

• Spec-first: haqiqat - spetsifikatsiyalarda (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• Deterministic & Testable: takrorlanadigan javoblar va fiksturlar.
• Docs-as-Code: hammasi VCSda, bitta versiya kod va konformans testlari bilan.
• Portability: konteynerlar, Helm/compose, tayyor manifestlar.

2) Referens-implementatsiya turlari

RI-Server: spetsifikatsiya boʻyicha server etaloni (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: mijoz etaloni (bitta-ikkita mashhur platforma) + misollar.
RI-Webhook Receiver: imzolangan vebxuklarni qayta ishlovchi (imzo, retralarni tekshirish).
RI-Adapters: xabar brokerlariga/voqea shinalariga adapterlar (Euro/Proto/JSON, Schema Registry).
RI-Data: maʼlumotlar toʻplami, maxfiylik profillari, «oltin» snapshotlar.

3) RI ombori arxitekturasi

ri/
specs/# OpenAPI/AsyncAPI/Proto/JSON-Schema server/# reference server src/
config/
docker/
helm/
client/# reference client/SDK + examples js/python/go/
conformance/# conformance runner, test cases, gold cases files/
fixtures/
golden/
samples/# end-to-end scripts, Postman/k6/Locust security/# test keys, policies, example signature docs/# manual, ADR, runbook, FAQ ci/# pipelines, configs, compatibility matrix tools/# generators, linters, circuit checkers

• Har bir reliz’vX tag. Y.Z’va artefaktlar (tasvirlar, chartlar, SDK).
• Har bir tikuv uchun - summa va imzo (supply-chain).
• CHANGELOG «buzuvchi» o’zgarishlar (breaking) belgisi bilan.

4) Speklar, kontraktlar va sxemalar

Transport: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
Semantika: xato kodlari, idempotentlik, kursorlar/paginatsiya, retraylar, deduplikatsiya.
Hodisalar: turi/versiyasi,’id’,’occurred _ at _ utc’,’partition _ key’, tartib invariantlari.
Signatura/xavfsizlik: OIDC/JWT belgilari, vebxuk imzosi (HMAC/EdDSA), kalitlar rotatsiyasi.
Sxem-kompatibiliti:’backward’forward’full’qoidalari, MAJOR’siz buzuvchi o’zgarishlarni taqiqlash.

5) Konformans-test

• (sxemalarni validatsiya qilish),
• xulq-atvor invariantlari (idempotentlik, saralash, kursorlar, TTL, retry-siyosatlar),
• xavfsizlik (imzolar, muddatlar, nonce/replay-himoya),
• vaqtinchalik jihatlar (UTC, RFC3339, DST),
• salbiy holatlar va chegara sharoitlari.

Oltin fayllar (golden): natijalar solishtiriladigan barqaror etalon javoblar/hodisalar.

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case. input)
res = http_call(target_url, req)
assert match_status(res. status, case. expect. status)
assert match_headers(res. headers, case. expect. headers)
assert match_body(res. json, golden_dir / case. id, allow_extra_fields=True)
for invariant in case. invariants:
assert invariant. holds(res, case. context)

consumer/sdk-js 1. 4server 1. 6, 1. 7server 2. 0 consumer/sdk-go 0. 9server 1. 5–1. 7   –
webhook-receiver 1. 1events v1events v2 (deprecated fields removed)

6) Prodakshen-minimum (ortiqchasiz)

Security: TLS by default, xavfsizlik sarlavhalari, CORS cheklovlari, limiterlar, anti-replay.
Observability: logi (struktural + PD maskalash), metrika (p50/p95/p99, error rate), treysing (korrelatsiya’request _ id’).
Config: hamma muhit oʻzgaruvchilari va fayllar orqali, konfiguratsiya sxemasi validatsiya qilinadi.
Perf-bazline: pullarning sog’lom sozlamalari, zanjir bo’yicha vaqtinchalik byudjet, coalescing bilan kesh.
Barqarorlik: jitter retraisi, circuit breaker, backpressure.

7) CI/CD va artefaktlar

1. Lint/yig’ish/testlar.

2. Spec validatsiyasi (OpenAPI/AsyncAPI/Proto-lint).

3. Spekdan SDK/stablar yaratish.

4. Konformans-ran:’ri-server’vs’cases’va «oltin».

5. Tasvirlarni yig’ish (SBOM, imzo), reyestrga e’lon qilish.

6. E2E ssenariylari (docker-compose/kind/Helm).

7. Dok-sayt va misollarni nashr etish.

• konteyner tasvirlari’ri-server’,’ri-webhook’,
• SDK-paketlar (npm/pypi/go),
• Helm-chart/compose-fayllar,
• zip «oltin fayllar» va konformans-ranner bilan.

8) Semplar, SDK va «how-to»

Ikkita mashhur stekda mini-ilova (masalan, Node. js/Go): autentifikatsiya → API chaqirish → xatolarni qayta ishlash → retrai → vebxuk.
How-to: idempotent POST, kursor paginatsiyasi, vebxuk imzosi, 429/503 ishlov berish.
«smoke-perf» uchun k6/JMeter profillar (yuk emas, balki asosiy salomatlik).

9) Versiyalash va evolyutsiya

SemVer: buzuvchi oʻzgarishlar → MAJOR; parchasiz qo’shish → MINOR; tuzatishlar → PATCH.
Deprecation-plan: spekulyar e’lonlar, ficha-bayroqlar, «soyali» conformance rejimi davri, so’ngra enforce.
Hodisalarning mosligi: konsumerlar notanish maydonlarni eʼtiborsiz qoldirishlari shart.

10) RIda xavfsizlik va maxfiylik

Test kalitlari va sirlari - faqat stend uchun; doklarda - almashtirish yo’riqnomasi.
Log’larda PDni yashirish; fiksturlarni anonimlashtirish profillari (PII → sintetika).
Demo-muhit artefaktlarining hayot vaqti siyosati (TTL, avto-tozalash).

11) RI uchun kuzatish va SLO

SLI/SLO RI: p95 <250 ms etalon stendida, error rate <0. 5%, qaramlik rad etilganda to’g "ri degradatsiya (semplada).
Dashbordlar: latency/Throughput/Errors + konformans-natijalar.
Vebxuklarni imzolash/tokenlarni tekshirish uchun Decision-loglar (muvaffaqiyatsizliklar sabablari).

12) Unumdorlik: «yetarli» bazlayn

’wrk/hey/k6’ profillari «issiq» va «sovuq» yoʻllarda.
Aniq pozitsiya: RI maksimal RPS boʻyicha raqobatlashmaydi, lekin namunaviy maqsadga (masalan, t3 uchun 500 RPS) bardosh berishi kerak. medium s p95 <200ms) - integratorlar uchun mo’ljal sifatida.

13) Foydalanish yo’riqnomasi (runbook)

Lokal ishga tushirish: compose/’ make up’.
K8s-deploy: Helm qiymatlari, sirlari, ingress, HPA.
Vebxuk imzosi kalitlarining roteyshni (dual-key davri).
Trablshuting: tez-tez xatolar va ularning sabablari (401, 403, 429, 503).

14) Boshqaruv va egalik qilish

Owners: mahsulot egasi + platforma (texnika) + xavfsizlik.
Relizlar taqvimi va buzuvchi oʻzgarishlarni muvofiqlashtirish oynasi.
RFC/ADR protokollarni oʻzgartirish uchun.

15) Tillarga/platformalarga moslashish

Tavsiya etilgan minimal: bitta yuqori darajali (JS/TS) va bitta tizimli (Go/Java).
Mapping turlari: sanalar/pul formatlari/decimal/baytlar to’plami qanday taqdim etiladi.
Har bir SDKda retraj/taymaut/pulni sozlash bo’yicha tavsiyalar.

16) Anti-patternlar

RI = «testsiz qum qutisi»: hech qanday konformans, hech qanday foyda yoʻq.
Speka kod va testlardan «alohida yashaydi» → tafovut.
«Oltin fayllar» va invariantlarning yo’qligi → fleykalar va xatti-harakatlar to’g’risidagi bahslar.
Fraymvork qaramligi: konteynerlashmasdan bitta kutubxona/bulutga qattiq bog’lanish.
Niqobsiz daftarlar, omborxonadagi kalitlar.
Xulq-atvor o’rniga perf-mikslar: «kim tezroq» o’lchashga urinish «kim to’g’ri» o’rniga.
Modulligi va artefaktlari bo’lmagan bitta ulkan binar/tasvir (SDK/chartlar/speklar).

17) Arxitektorning chek-varaqasi

1. Speka - kanonik va validatsiya qilinadigan? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. To’liq misollarga ega bo’lgan RI-server va kamida bitta RI-client/SDK bormi?
3. Konformans-ranner, keyslar, «oltin fayllar», negativlar va invariantlar tayyormi?
4. CI/CD rasmlar, SDK, veb-sayt yigʻadi, conformance va e2e ishga tushiradimi?
5. Andoza xavfsizlik: TLS, imzolar, chegaralar, PD yashirish?
6. Kuzatish darajasi: RI uchun loglar/metriklar/treyslar, dashbordlar va SLO?
7. Perf-bazline hujjatlashtirilganmi?
8. SemVer versiyasi, moslik matritsasi, deprecation-protsedurasi?
9. Runbook va lokal/klaster ishga tushirish - bitta bosishda?
10. Egalari, relizlar taqvimi, RFC/ADR oqimi aniqlanganmi?

18) Mini-misol: referens-vebxuk (psevdokod)

python def verify_webhook(request, keys):
sig = request. headers["X-Signature"]
ts = int(request. headers["X-Timestamp"])
if abs(now_utc(). epoch - ts) > 300: return 401 # replay window body = request. raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys. active_and_previous()):
return 401 event = json. loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

Test-keys: vaqt oynasi, imzoning to’g "riligini (joriy va oldingi kalit),’event bo’yicha idempotentligini tekshiradi. id’, negativlar (buzilgan imzo, muddati o’tgan’ts’).

Xulosa

Referens-implementatsiya - bu tizim xulq-atvori kanoni: kod, testlar va artefaktlar bilan tasdiqlangan yagona speka. Yaxshi RI integratsiyani tezlashtiradi, protokollarning noaniqligini olib tashlaydi, tekshiriladigan muvofiqlikni ta’minlaydi va minimal xavfsizlik, kuzatish va ishlash standartlarini belgilaydi. Uni muhandislik skeletingizning bir qismiga aylantiring - mahsulotlaringiz, sheriklaringiz va ekotizimingiz tezroq va ishonchli harakat qiladi.