SDK dizayn va tillarni qo’llab-quvvatlash

1) SDK maqsadlari va muvaffaqiyat mezonlari

Developer Experience (DX): intuitiv API, tillar o’rtasidagi yagona semantika.
Ishonchlilik: taymautlar/retryalar/idempotentlik «qutidan».
Xavfsizlik: sirlar, imzolar, TLS, proksi/企业 muhitga moslik.
Kuzatish darajasi: loglar, metriklar, til uchun standart asboblardagi trassalar.
Iqtisodiyot: minimal egress/CPU, samarali paginatsiya, batchi.
Barqarorlik: qattiq semver, teskari muvofiqlik, LTS filiallari.

2) Arxitektura prinsiplari

1. Thin client, strong contracts: SDK (REST/gRPC) ni maxfiy biznes mantiqsiz oʻrash.
2. Unified surface: bir xil tushunchalar (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Safe by default: oqilona taymautlar, eksponensial backoff + jitter, takrorlashlardan himoya qilish.
4. Config layering: ENV → -fayl → konstruktor → usul parametrlari.
5. Pluggable transport: HTTP/gRPC oʻzgaruvchan, proksi/ bilan mos keladi.
6. Testability: interfeyslar/soxta, dependency injection, record-replay.
7. Xato I18n: mashina’error _ code’barqaror; xabarlar mahalliylashtiriladi.
8. Accessibility: Osinxron variantlar (odatda’AsyncClient’).
9. Security-first: sirlar, agar kerak bo’lsa, loglarga, PII tahririyatga, FIPS mos keladigan kriptoblioteklarga kirmaydi.

3) Qo’llab-quvvatlash jadvali va imkoniyatlar pariteti

4) API bazaviy yuzasi (kanonik model)

Umumiy mohiyat

Client: transport, kalitlar, retraylar, telemetry hooks.
Request/Response: tipik xavfsiz modellar/DTO, paginatsiya/kursorlar.
Error: yagona sinf s’status’,’error _ code’,’trace _ id’,’retriable’.
Paginator/Iterator: sahifa/kursorlarning dangasa saralanishi.
WebhookVerifier: HMAC/mTLSni tekshirish.

Mini-misol (TypeScript)

ts const client = new GambleHubClient({
apiKey: process. env. GH_API_KEY!,
timeoutMs: 10_000,
retries: { max: 5, strategy: "expo-jitter" }
});

const { items, nextCursor } = await client. reports. list({ from, to, cursor });
for await (const report of client. reports. iter({ from, to })) { /... / }

Mini-misol (Python, async)

py from gamblehub import AsyncClient, WebhookVerifier

client = AsyncClient(api_key=API_KEY, timeout=10, retries={"max":5})
async for user in client. users. iter(updated_after=ts):
...

verifier = WebhookVerifier(secret=WEBHOOK_SECRET)
if verifier. verify(headers, body): ack()

5) Konfiguratsiya va bajarish muhiti

ENV: `GH_API_KEY`, `GH_ENDPOINT`, `GH_TIMEOUT_MS`, `HTTP_PROXY/HTTPS_PROXY`, `GH_REGION`.
Konstruktor: ENVni qayta belgilaydi.
Per-call overrides: usul darajasida taymaut/retraj.
TLS/mTLS: sertifikat/kalit, pinning CA kerak boʻlganda.
Ulanish pullari: keep-alive, HTTP/2, parallellikni cheklash.

6) Qutidan xavfsizlik

Sirlar: noto’g’ri, stack traces-da yashirish; redaction ``.
Imzolar: Vebxuklar uchun HMAC,’X-Key-Id ’/kalitlarni rotatsiya qilish, «ikkita kalitni» qo’llab-quvvatlash active/next.
Idempotentlik: write operatsiyalari uchun shaffof’Idempotency-Key’qurilmasi (qayta ishga tushirish xavfsiz).
RBAC/Scopes: sotib olish uchun qulay roʻyxatlar/konstantalar.
PII siyosati: loglarni tahrirlashda standart interfeyslar.

7) Ishonchlilik: taymautlar, retryalar, bek-off

Andoza taymaut: 10-15s; 3-5s konnekt.
Retry: 5xx/408/429 uchun (’Retry-After’ni hurmat qilish), eksponensial backoff + jitter, urinishlar/vaqt chegarasi.
Circuit-breaker: ixtiyoriy ravishda SDKda (yoki tashqi liblar bo’yicha tavsiyalar).
Idempotent write: kalit boʻyicha avtomatik takrorlash; to’qnashuvlar → ko’tarish’409 IDEMP_REPLAY'.

8) Paginatsiya, kursorlar va striming

Kursor/iterator: dangasa ortiqcha, tranziyent xatolarda avto-takrorlash.
Keyset-paginatsiya: barqaror tartibga solish’(updated_at,id)’.
Backpressure: bir vaqtning o’zida so’rov limiti; в async-SDK — `async for`/`channels`.
Striming (mavjud): SSE/WebSocket/gRPC-stream avto-reconnect va’sequence’deb nomlangan.

9) Xatolar va kontrakt

• `ApiError` (базовый) → подтипы: `AuthError(401)`, `PermissionError(403)`, `NotFound(404)`, `Conflict(409)`, `RateLimit(429)`, `ValidationError(422)`, `ServerError(5xx)`.
• Свойства: `status`, `error_code`, `message`, `trace_id`, `retriable`, `details`.
• Best practice: xabarlarni oʻqish mumkin,’error _ code’- barqaror.

10) Til idiomalari

TypeScript/JS

Promise-based + paginatsiya uchun generatorlar; ESM + CJS paketlari.
Tree-shaking, minimal polifillar, abort-signallar (’AbortController’).

Python

Sync + Async (aiohttp/httpx), kontekst-menejerlar,’pydantic’modellar (yoki dataclasses).
Wheels для linux/macos/windows; proxies/NO_PROXY qo’llab-quvvatlash.

Java

’CompletableFuture’ (zarurat boʻlganda),’AutoCloseable’,’Duration’,’Executor’.
HTTP client: `java. net. http’yoki OkHttp; SLF4J uchun maʼlumot.

Go

Kontekstlar’context. Context`, `http. Client’s tuned Transport, testlar uchun interfeyslar.
Error wrapping (`fmt. Errorf («% w», err)’), sentinel xato semantikasi.

.NET

`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.
Polly siyosati (retry/circuit-breaker).

... va h.k. uchun PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) Logirovka, metrika, trastirovka

Logi: darajalar (ERROR/WARN/INFO/DEBUG), korellatsiya’trace _ id’, sezgir maʼlumotlarni oʻchirish.
Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.
Trassalar: OpenTelemetry hooks (API chaqiruviga span, endpoint, status, retry atributlari).
Debug-mode:’GH _ SDK _ DEBUG = 1’- HTTP sarlavhalarini (sirsiz) va vaqtlarni bosib chiqarish.

12) Hujjatlar va misollar

Quickstart 5 daqiqa: auth, birinchi so’rov, paginatsiya, ishlov berish 429.
Cookbook: vebxukki (imzoni tekshirish), idempotent write, replay.
API ma’lumotnomasi: OpenAPI/Protobuf avtogen, ammo «qo’lda» misollar bilan.
Snippets: mashhur vazifalar uchun tayyor kod boʻlaklari (Python/TS/Java/Go/.NET).

13) Generatsiya vs qo’lda kodlash

Kombinatsiyalangan yondashuv: codegen (modellar/mijozlar) + ergonomics/idempotentlik/paginatorlar uchun qo’lda ishlatiladigan «tutqichlar».
Namunalar: usullarning yagona nomlari (’create/get/list/update/delete’), stab. signatura.
Regen (CI-geyt) dan keyin «diff-moslik» ni tekshirish.

14) Versiyalash, muvofiqlik va depreksiya

SemVer: X.Y.Z. Sinuvchi - faqat major.
Barqarorlik siyosati: minor relizlar - dalalar/usullarni qo’shadi, shartnomalarni o’zgartirmaydi.
Deprecation: izohlar/ @Deprecated/Obsolete atributlari, rantaymdagi ogohlantirishlar har bir jarayonda bir marta, deraza ≥ 90 kun.
LTS-filiallar: yangi fichsiz.

15) Relizlar va yetkazib berish zanjiri

CI/CD: linterlar/formatterlar, unit + integration, kontrakt-testlar, e2e qum qutisiga qarshi.
Obʼektlarning imzosi: Sigstore/GPG, relizlardagi checksums.
Nashr: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems bilan changelog va release notes.
SemVer gate: Ochiq API mosligini avto tekshirish (masalan,’apiregistry diff’).

16) Test (sifat matritsasi)

Unit: modellar, seriallashtirish, validatsiya, retray/taymautlar.
Contract: OpenAPI/Protobuf sxemalariga qarshi (negative/edge cases).
Integration: qarshi sandbox (idempotentlik, 429/5xx, webhooks).
Load/soak: paginatsiya/oqim, backpressure.
Fuzz: maydon/sarlavha/vaqt chegarasi.
Compat: eski SDK yangi API va aksincha.
Smoke-pack: CI regressi uchun 5 daqiqa.

17) Telemetriya va maxfiylik siyosati

Opsion-opt-in: PIIsiz agregatsiyalangan SDK metriklarini (versiyasi, tili, maqomi) yig’ish.
:’telemetry: off’anonymized’full’(andoza off/anonymized).
Shaffoflik: nima va nima uchun ketayotganini hujjatlashtiring; oʻchirishni belgilang.

18) Unumdorlik va FinOps

Batching: kichik soʻrovlarni birlashtirish; RPSni cheklash; gzip/br.
Kachirlash ETag/If-None-Match, shartli GET.
Tejamkor modellar: hamma narsani xotiraga yuklash o’rniga dangasa iteratorlar.
«DDOSit» API boʻlmasligi uchun «max _ concurrency» chegarasi bilan parallellik.

19) SDKning namunaviy komponentlari (skeletlar)

Error (TypeScript)

ts export class ApiError extends Error {
constructor(
readonly status: number,
readonly errorCode: string,
readonly traceId?: string,
readonly retriable?: boolean,
readonly details?: unknown
) { super(`${status} ${errorCode}`); }
}

Paginator (Python)

py class Paginator(Generic[T]):
def __init__(self, fetch_page):
self._fetch = fetch_page self._cursor = None async def __aiter__(self):
while True:
page = await self._fetch(self._cursor)
for item in page. items:
yield item if not page. has_more: break self._cursor = page. next_cursor

WebhookVerifier (Go)

go func Verify(body []byte, signatureHeader, secret string) bool {
parts:= strings. SplitN(signatureHeader, "=", 2)
mac:= hmac. New(sha256. New, []byte(secret))
mac. Write(body)
expected:= base64. StdEncoding. EncodeToString(mac. Sum(nil))
return hmac. Equal([]byte(parts[1]), []byte(expected))
}

20) Qo’llab-quvvatlash, SLA va hamjamiyat

SDK bo’yicha SLA: tanqidiy xatolar - fix ETA, aloqa kanallari, muvofiqlik matritsasi (SDK API).
Issue templates: bug/feature/question, auto-triage.
Roadmap/labels: «good first issue», «help wanted».
Security policy: `SECURITY. md’, zaifliklar to’g "risidagi hisobotlar uchun kanal, zarurat bo’lganda CVE.

21) SDK sifat chek-varaqasi

• Yagona model xatosi (’status’,’error _ code’,’trace _ id’,’retriable’).
• Taymautlar/retrajlar/jitter, hurmat’Retry-After’.
• Idempotentlik write, avtomatik’Idempotency-Key’.
• Kursor, dangasa iteratorlar/oqimlar.
• WebhookVerifier HMAC/mTLS va bobosi bilan.
• ENV/konstruktor/moslamalar orqali moslash.
• Logografiya/metrika/OTel-xuki, sirsiz debug-rejim.
• SemVer, 90 kundan ≥ depreksiya, LTS filiallari.
• Mashhur vazifalar bo’yicha to’liq misollar va Cookbook.
• CI tillari orasidagi paritet matritsasi.

22) Joriy etish rejasi (3 ta iteratsiya)

1. MVP (2-3 hafta): bazaviy Client, auth, 3-5 asosiy endpint, paginatsiya, yagona xato-model, retrai/taymautlar; TS+Python.
2. Scale (3-5 hafta): Java/Go/.NET, WebhookVerifier, idempotentlik write, telemetriya hooks, OpenAPI modellarini yaratish.
3. Pro (uzluksiz): striming/SSE/gRPC, perf-optimallashtirish, LTS-filiallar, kengaytirilgan Cookbook, migratsiya/depreksiya vositalari.

23) Mini-FAQ

Hamma narsani yaratishni yoki qoʻlingiz bilan yozishni istaysizmi?
Modellarni/mijozlarni yarating, ergonomics esa (paginatorlar, retraylar, idempotentlik, qulay belgilar) - qo’lda.

Alohida async-SDK kerakmi?
В Python — да (`AsyncClient`); JSda - andoza; v.NET/Java - iloji boricha asinxron qoʻngʻiroqlar.

Til tengligini qanday saqlash kerak?
CIdagi fich matritsasi, «kamar bo’yicha» relizlari (TS → Py → Java → Go → .NET) avto-report bilan «orqada».

Jami

Kuchli SDK - bu barcha tillarda bir xil bo’lgan yagona yuza, ishonchli defoltlar va oldindan aytib bo’ladigan shartnomalar. Ishlab chiquvchilarga xavfsiz quti sozlamalari, tushunarli xato-model, qulay paginatsiya va vebxuklarni tekshirish, sifatli hujjatlar va qatʼiy semver bilan yakunlash imkonini bering. Shunda integratsiya tez, qo’llab-quvvatlash arzon, ekotizim esa barqaror va ko’lamli bo’ladi.