SDK dil dizaýny we goldawy
1) SDK maksatlary we üstünlik ölçegleri
Developer Experience (DX): duýgur API, dilleriň arasyndaky ýeke-täk semantika.
Ygtybarlylygy: taýmautlar/retraýlar/" gutudan "idempotentlik.
Howpsuzlyk: syrlar, gollar, TLS, proksi/企业 gurşaw bilen gabat gelmek.
Syn edilişi: dil üçin standart gurallarda loglar, metrikler, ýollar.
Ykdysadyýet: minimal egress/CPU, täsirli paginasiýa, batchi.
Durnuklylyk: berk semver, ters gabat gelmek, LTS şahalary.
2) Binagärlik ýörelgeleri
1. Thin client, strong contracts: SDK gizlin iş logikasyz teswirnamanyň (REST/gRPC) üstündäki örtük.
2. Unified surface: birmeňzeş düşünjeler (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Safe by default: akylly wagtlar, eksponensial backoff + jitter, gaýtalanmakdan gorag.
4. Config layering: ENV → -faýl → dizaýner → usulyň parametrleri.
5. Pluggable transport: HTTP/gRPC çalşylýar, proxy/ birikdirmeleri bilen gabat gelýär.
6. Synag ukyby: interfeýsler/galplyklar, dependency injection, record-replay.
7. Hata I18n: maşyn 'error _ code' durnukly; habarlar lokallaşdyrylýar.
8. Accessibility: "AsyncClient" (adatça 'AsyncClient') görnüşi.
9. Security-first: syrlar girelgelere girmeýär, PII-redaksiýa, zerur bolan halatynda FIPS-gabat gelýän kripto-bibliotekalar.
3) Goldaw tablisasy we mümkinçilikleriň deňligi
4) API esasy ýüzi (kanoniki model)
Umumy zatlar
Müşderi: ulaglary, açarlary, retraýlary, telemetry hooks sazlamak.
Request/Response :/DTO, paginasiýa/kursorlar.
Error: 'status', 'error _ code', 'trace _ id', 'retriable'.
Paginator/Iterator: sahypalaryň/kursorlaryň ýaltalygy.
WebhookVerifier: HMAC/mTLS barlagy.
Kiçi görelde (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 })) { /... / }Kiçi görelde (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) Konfigurasiýa we ýerine ýetiriş gurşawy
ENV: `GH_API_KEY`, `GH_ENDPOINT`, `GH_TIMEOUT_MS`, `HTTP_PROXY/HTTPS_PROXY`, `GH_REGION`.
Dizaýner: ENV-ni täzeden kesgitleýär.
Per-call overrides: usul derejesinde wagt/retra.
TLS/mTLS: şahadatnama/açara ýol, zerur bolsa CA pinning.
Baglanyşyk howuzlary: keep-alive, HTTP/2, paralelligi çäklendirmek.
6) Gutudan howpsuzlyk
Syrlar: stack traces-da gizlemäň; redaction ``.
Gollar: Webhook üçin HMAC, 'X-Key-Id '/açar aýlawy, "iki açar" aktive/next goldawy.
Idempotentlik: write amallary üçin "Idempotency-Key" aç-açan gurnama (täzeden başlamak howpsuz).
RBAC/Skopes: satyn almak üçin amatly sanaw/sabitler.
PII-syýasat: logirlemekde redaktirlemegiň standart interfeýsleri.
7) Ygtybarlylyk: Taýmautlar, retraýlar, arka-off
Adaty wagt: 10-15s; konnekt 3-5c.
Retrailer: 5xx/408/429 üçin ('Retry-After' -e hormat goýmak), eksponensial backoff + jitter, synanyşyk/wagt çäkleri.
Circuit-breaker: SDK-da goşmaça (ýa-da daşarky liblar boýunça teklipler).
Idempotent write: açar boýunça awtomatiki gaýtalamak; çaknyşyklar → götermek '409 IDEMP_REPLAY'.
8) Paginasiýa, kursorlar we akym
Kursor/iterator: ýalta artykmaç, geçiş ýalňyşlyklarynda awto-gaýtalanmalar.
"Keyset-pagination": "(updated_at,id)".
Backpressure: bir wagtyň özünde soramagyň çägi; в async-SDK — `async for`/`channels`.
Akym (bar ýerinde): SSE/WebSocket/gRPC-stream awto-reconnect we 'sequence' sözbaşy bilen.
9) Ýalňyşlyklar we şertnama
Bitewi iýerarhiýa:- `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: Habarlar - adam okalýar, 'error _ code' - durnukly.
10) Dil idiomalary
TypeScript/JS
Promise-based + paginasiýa üçin generatorlar; ESM + CJS paketleri.
Tree-shaking, minimal polifiller, abort signallary ('AbortController').
Python
Sync + Async (aiohttp/httpx), kontekst-dolandyryjylar, 'pydantic' modelleri (ýa-da dataclasses).
Wheels для linux/macos/windows; proxies/NO_PROXY goldamak.
Java
'CompletableFuture' (zerur), 'AutoCloseable', 'Duration', 'Executor'.
HTTP client: `java. net. http 'ýa-da OkHttp; SLF4J girelgeleri.
Go
Kontekstler 'context. Context`, `http. Client's tuned Transport, synaglar üçin interfeýsler.
Error wrapping (`fmt. Errorf ("% w", err) '), sentinel ýalňyşlyklarynyň semantikasy.
.NET
`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.
Polly syýasatlary (retry/circuit-breaker).
... we ş.m. PHP/Ruby üçin (PSR-18, Faraday/Net:: HTTP).
11) Logirleme, metrika, yzarlama
Loglar: derejeler (ERROR/WARN/INFO/DEBUG), korelýasiýa 'trace _ id', duýgur maglumatlary öçürmek.
Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.
Ýollar: OpenTelemetry hooks (API çagyryşyna span, endpoint, status, retry atributlary).
Debug-mode: üýtgeýän gurşaw 'GH _ SDK _ DEBUG = 1' - HTTP sözbaşylaryny (syrsyz) we wagtlary çap etmek.
12) Resminamalar we mysallar
Quickstart 5 minut: auth, birinji haýyş, paginasiýa, gaýtadan işlemek 429.
Cookbook: webhuklar (goly barlamak), idempotent write, bellik.
API gollanmasy: OpenAPI/Protobuf-dan awtogen, ýöne "el" mysallary bilen.
Snippets: meşhur meseleler üçin taýýar kod bölekleri (Python/TS/Java/Go/.NET).
13) Nesil vs el bilen kodlamak
Kombinirlenen çemeleşme: codegen (modeller/müşderiler) + ergonomics/idempotentlik/paginatorlar üçin "ruçkalar".
Şablonlar: usullaryň birmeňzeş atlary ('create/get/list/update/delete'), stab. belgiler.
Regenden soň "diff-laýyklygy" barlamak (CI-gate).
14) Wersiýalaşdyrmak, gabat gelmek we deprekasiýa
SemVer: X.Y.Z. Döwmek - diňe major.
Durnuklylyk syýasaty: kiçi relizler - meýdanlary/usullary goşýarlar, şertnamalary üýtgetmeýärler.
Deprecation: düşündirişler/ @Deprecated/Obsolete atributlary, ýüz tutma duýduryşlary her proses üçin bir gezek, penjire ≥ 90 gün.
LTS şahalary: kritfiksleriň arka porty (täze fiçsiz).
15) Goýberişler we eltip bermek zynjyry
CI/CD: linterler/formaterler, unit + integration, şertnama-synaglar, e2e garşy sandyk gutusy.
Artefaktlaryň goly: Sigstore/GPG, relizlerde checksums.
Neşir: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems with changelog and release notes.
SemVer gate: public API-iň awto-barlagy (mysal üçin 'apiregistry diff').
16) Synag (hil matrisi)
Unit: modeller, serializasiýa, tassyklama, retrailer/wagtlar.
Contract: OpenAPI/Protobuf shemalaryna garşy (negative/edge cases).
Integration: vs sandbox (idempotentlik, 429/5xx, webhooks).
Load/soak: paginasiýa/akym, backpressure.
Fuzz: meýdan/sözbaşy/wagt çäkleri.
Compat: köne SDK täze API we tersine.
Smoke-pack: CI-de regresi tutmak üçin 5 minut.
17) Telemetriýa we gizlinlik syýasaty
Option-opt-in: PII-siz SDK (wersiýa, dil, statuslar) jemlenen metrikleri ýygnamak.
: 'telemetry: off' anonymized 'full' (default off/anonymized).
Aç-açanlyk: nämäni we näme üçin ýygnanýandygyny resminamalaşdyryň; öçürmek belgisini beriň.
18) Öndürijilik we FinOps
Batching: ownuk soraglary birleşdirmek; RPS çäklendirmek; gzip/br.
ETag/If-None-Match kesmek, şertli GET.
Tygşytly modeller: ýatda hemme zady ýüklemegiň ýerine ýalta iteratorlar.
"DDOS" API-den gaça durmak üçin "max _ concurrency" çäkli paralellik.
19) SDK-nyň nusgawy komponentleri (skeletler)
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_cursorWebhookVerifier (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) Goldaw, SLA we jemgyýet
SDK boýunça SLA: kritiki bökdençlikler - fix ETA, aragatnaşyk kanallary, laýyklyk matrisi (SDK API).
Issue templates: bug/feature/question, auto-triage dil/wersiýa boýunça.
Roadmap/labels: «good first issue», «help wanted».
Security policy: `SECURITY. md ', gowşaklyk hasabatlary üçin kanal, zerur bolan halatynda CVE.
21) SDK hiliniň çek-sanawy
- Ýeke-täk hata ('status', 'error _ code', 'trace _ id', 'retriable').
- Wagt/retrailer/jitter, hormat 'Retry-After'.
- Write idempotentligi, awtomatiki "Idempotency-Key".
- Kursor, ýalta iteratorlar/akymlar.
- WebhookVerifier HMAC/mTLS we dedup bilen.
- ENV/dizaýner/parametrler arkaly konfigurasiýa.
- Logistika/metrika/OTel-huki, syr ýok debug-mode.
- SemVer, deprekasiýa ≥ 90 gün, LTS şahalary.
- Meşhur meseleler boýunça doly mysallar we Cookbook.
- CI-de dilleriň arasyndaky paritet matrisi.
22) Durmuşa geçirmek meýilnamasy (3 iterasiýa)
1. MVP (2-3 hepde): Esasy Client, auth, 3-5 esasy endpoint, paginasiýa, ýeke-täk ýalňyşlyk-model, retrailer/wagt; TS+Python.
2. Scale (3-5 hepde): Java/Go/.NET, WebhookVerifier, write idempotentligi, telemetriýa hooks, OpenAPI-den modelleri döretmek.
3. Pro (üznüksiz): akym/SSE/gRPC, perf-optimizasiýa, LTS şahalary, giňeldilen Cookbook, migrasiýa/deprekasiýa gurallary.
23) Mini-FAQ
Hemme zady döretmek ýa-da el bilen ýazmak?
Modelleri/müşderileri dörediň, ergonomics bolsa (paginatorlar, retralar, idempotentlik, amatly alamatlar) - el bilen.
Aýratyn async-SDK gerekmi?
В Python — да (`AsyncClient`); JS - adaty; v. NET/Java - mümkin boldugyça asenkron jaňlar.
Dilleriň deňligini nädip saklamaly?
CI-de matrisa fiç, "kemer boýunça" (TS → Py → Java → Go → .NET) "näme yzda" awto-habary bilen çykarylýar.
Jemi
Güýçli SDK - ähli dillerde birmeňzeş bolan ýeke-täk ýer, ygtybarly defoltlar we öňünden aýdyp boljak şertnamalar. Işläp düzüjilere "gutudan" ygtybarly sazlamalary, düşnükli ýalňyşlyk-model, amatly paginasiýa we webhuklary barlamagy beriň, ony hil resminamalary we berk semver bilen tamamlaň. Şonda integrasiýa çalt, goldaw arzan we ekosistema durnukly we masştably bolar.