SDK дизайн және тілдерді қолдау

1) SDK мақсаттары және табыс критерийлері

Developer Experience (DX): интуитивті API, тілдер арасындағы бірыңғай семантика.
Сенімділік: «қораптан» таймауттар/ретрациялар/икемділік.
Қауіпсіздік: құпиялар, қолтаңбалар, TLS, proksi/企业 орталармен үйлесімділік.
Бақылау қабілеті: логи, метрика, тілге арналған стандартты құралдардағы трассалар.
Экономика: минимум egress/CPU, тиімді пагинация, батчи.
Тұрақтылық: қатаң semver, кері үйлесімділік, LTS-тармақтары.

2) Сәулет қағидаттары

1. Thin client, strong contracts: SDK жасырын бизнес-логикасыз хаттамаға (REST/gRPC) орау.
2. Unified surface: бірдей ұғымдар (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Safe by default: ақылға қонымды таймауттар, экспоненциалды backoff + jitter, қайталанудан қорғау.
4. Config layering: ENV → -файл → құрастырушы → әдіс параметрлері.
5. Pluggable transport: HTTP/gRPC ауыстырылатын, прокси/ қосылымдарымен үйлесімді.
6. Testability: интерфейстер/фейктер, dependency injection, record-replay.
7. Қате I18n: машиналық 'error _ code' тұрақты; хабарлар жергілікті.
8. Accessibility: ыңғайлы жерде асинхронды нұсқалар (әдетте 'AsyncClient').
9. Security-first: құпиялар логиге түспейді, PII-редакция, қажет болған жағдайда FIPS-үйлесімді криптобиблиотекалар.

3) Қолдау кестесі және мүмкіндіктер тепе-теңдігі

4) API базалық беті (каноникалық модель)

Ортақ мәні

Клиент: көлікті, кілттерді, ретрайлерді, telemetry hooks баптау.
Request/Response: типтік қауіпсіз модельдер/DTO, пагинация/курсорлар.
Error: бірыңғай сынып с 'status', 'error _ code', 'trace _ id', 'retriable'.
Paginator/Iterator: беттерді/меңзерлерді жалқаулықпен іріктеу.
WebhookVerifier: HMAC/mTLS тексеру, 'event _ id' дедупы.

Шағын мысал (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 })) { /... / }

Шағын мысал (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) Конфигурация және орындау ортасы

ENV: `GH_API_KEY`, `GH_ENDPOINT`, `GH_TIMEOUT_MS`, `HTTP_PROXY/HTTPS_PROXY`, `GH_REGION`.
Құрастырушы: ENV қайта анықтайды.
Per-call overrides: әдіс деңгейіндегі таймаут/ретра.
TLS/mTLS: сертификат/кілт жолы, қажет болған жағдайда CA pinning.
Қосылыс пулдары: keep-alive, HTTP/2, параллелизмді шектеу.

6) Қораптан қауіпсіздік

Құпиялар: логикалық емес, stack traces жасыру; redaction ``.
Қолтаңбалар: Вебхуктар үшін HMAC, 'X-Key-Id '/кілттерді ротациялау, «екі кілтті» қолдау active/next.
Теңсіздік: write-операцияларына арналған 'Idempotency-Key' мөлдір қондырғы (қайта іске қосу қауіпсіз).
RBAC/Scopes: сатып алу үшін ыңғайлы санамалар/константалар.
PII-саясат: Логиндеу кезінде стандартты өңдеу интерфейстері.

7) Сенімділік: таймауттар, ретрациялар, бэк-офф

Әдепкі уақыт: 10-15с; коннект 3-5с.
Ретраилер: 5xx/408/429 үшін ('Retry-After' құрметтеу), экспоненциалды backoff + jitter, әрекет/уақыт шегі.
Circuit-breaker: SDK-да қосымша (немесе сыртқы либалар бойынша ұсынымдар).
Теңсіздік write: кілт бойынша автоматты түрде қайталау; коллизиялар → көтеру '409 IDEMP_REPLAY'.

8) Пагинация, курсорлар және стриминг

Курсор/итератор: жалқау іріктеу, транзиенттік қателер кезіндегі авто-қайталаулар.
Keyset-pagination: тұрақты реттеу '(updated_at,id)'.
Backpressure: бір уақытта сұрау лимиті; в async-SDK — `async for`/`channels`.
Стриминг (бар жерде): SSE/WebSocket/gRPC-stream авто-reconnect және «sequence» дедупы.

9) Қателер және келісімшарт

• `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: хабар - адам оқитын, 'error _ code' - тұрақты.

10) Тілдік идиомалар

TypeScript/JS

Promise-based + пагинация генераторлары; ESM + CJS пакеттері.
Tree-shaking, минималды полифилдер, abort-сигналдар ('AbortController').

Python

Sync + Async (aiohttp/httpx), контексттік менеджерлер, 'pydantic' модельдері (немесе dataclasses).
Wheels для linux/macos/windows; proxies/NO_PROXY қолдау.

Java

'CompletableFuture' (қажеттілігіне қарай), 'AutoCloseable', 'Duration', 'Executor'.
HTTP client: `java. net. http 'немесе OkHttp; Логтардың SLF4J.

Go

'context. Context`, `http. Client's tuned Transport, тест интерфейстері.
Error wrapping (`fmt. Errorf («% w», err) '), sentinel қателер семантикасы.

.NET

`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.
Polly (retry/circuit-breaker) саясаты.

... және т.б. PHP/Ruby үшін (PSR-18, Faraday/Net:: HTTP).

11) Логика, метрика, трассировка

Логи: деңгейлер (ERROR/WARN/INFO/DEBUG), 'trace _ id' корелляциясы, сезімтал деректерді ажырату.
Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.
Трассалар: OpenTelemetry hooks (API шақыруына span, endpoint, status, retry төлсипаттары).
Debug-mode: 'GH _ SDK _ DEBUG = 1' орта айнымалысы - HTTP тақырыптарын (құпиясыз) және уақытты басып шығару.

12) Құжаттама және мысалдар

Quickstart 5 минут: auth, бірінші сұрау, пагинация, өңдеу 429.
Cookbook: вебхактар (қолтаңбаны тексеру), теңсіздік write, реплика.
API анықтамалығы: OpenAPI/Protobuf автогені, бірақ «қол» мысалдары бар.
Snippets: танымал тапсырмалар үшін дайын код бөліктері (Python/TS/Java/Go/.NET).

13) Генерация vs қолмен кодтау

Аралас тәсіл: codegen (модельдер/клиенттер) + ergonomics/демпотенттік/пагинаторларға арналған қол «тұтқалары».
Үлгілер: әдістердің бірыңғай атаулары ('create/get/list/update/delete'), стаб. сигнатуралар.
Регеннен кейін «diff-үйлесімділігін» тексеру (CI-гейт).

14) Нұсқалау, үйлесімділік және депрекация

SemVer: X.Y.Z. Сыну - тек major.
Тұрақтылық саясаты: шағын релиздер - өрістерді/әдістерді қосады, келісімшарттарды өзгертпейді.
Deprecation: аннотациялар/ @Deprecated/Obsolete атрибуттары, процеске бір рет рантаймдағы ескертулер, терезе ≥ 90 күн.
LTS-тармақтары: критфикстер backport (жаңа сызықсыз).

15) Релиздер және жеткізу тізбегі

CI/CD: линтерлер/форматорлар, unit + integration, келісімшарт-тестілер, құмсалғышқа қарсы e2e.
Шығарылымдардағы артефактілердің: Sigstore/GPG, checksums қолы.
Жариялау: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems changelog және release notes.
SemVer gate: жария API сыйысымдылығын автоматты түрде тексеру (мысалы, 'apiregistry diff').

16) Тестілеу (сапа матрицасы)

Unit: модельдер, серияландыру, валидация, ретраи/таймауттар.
Contract: OpenAPI/Protobuf схемаларына қарсы (negative/edge cases).
Integration: sandbox қарсы (теңсіздік, 429/5xx, webhooks).
Load/soak: пагинация/стрим, backpressure.
Fuzz: өрістер/тақырыптар/уақыт шектері.
Compat: ескі SDK жаңа API және керісінше.
Smoke-pack: CI регресін ұстау үшін 5 минут.

17) Телеметрия және жекешелендіру саясаты

Опциондық-opt-in: PII-сіз SDK (нұсқа, тіл, мәртебе) біріктірілген метриктерін жинау.
: 'telemetry: off' anonymized 'full' (әдепкі off/anonymized).
Ашықтық: не және не үшін жиналатынын құжаттаңыз; өшіру құсбелгісін беріңіз.

18) Өнімділік және FinOps

Batching: ұсақ сұрауларды біріктіру; RPS лимиттеу; gzip/br.
ETag/If-None-Match кэштеу, шартты GET.
Үнемді модельдер: жадқа бәрін жүктеудің орнына жалқау итераторлар.
API «DDOS» болмауы үшін «max _ concurrency» лимитімен параллелизм.

19) SDK типтік компоненттері (скелеттер)

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}`); }
}

Пагинатор (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) Қолдау, SLA және қоғамдастық

SDK бойынша SLA: сыни жүктер - fix ETA, байланыс арналары, үйлесімділік матрицасы (SDK API).
Issue templates: bug/feature/question, тіл/нұсқа бойынша auto-triage.
Roadmap/labels: «good first issue», «help wanted».
Security policy: `SECURITY. md ', осалдықтар туралы есептер арнасы, қажет болған жағдайда CVE.

21) Сапа чек-парағы SDK

• Бірыңғай қате моделі ('status', 'error _ code', 'trace _ id', 'retriable').
• Таймауттар/ретрайлер/jitter, құрмет 'Retry-After'.
• Write сәйкестігі, автоматты түрде 'Idempotency-Key'.
• Курсормен пагинация, жалқау итераторлар/ағындар.
• WebhookVerifier HMAC/mTLS және дедуппен.
• ENV/құрастырушы/параметрлері арқылы конфигурациялау.
• Логин/метрика/OTel-huki, құпиясыз дебуг режимі.
• SemVer, 90 күнге ≥ депрекация, LTS-тармақтары.
• Танымал тапсырмалар бойынша толық мысалдар мен Cookbook.
• CI-дегі тілдер арасындағы паритет матрицасы.

22) Енгізу жоспары (3 итерация)

1. MVP (2-3 апта): базалық Client, auth, 3-5 негізгі эндпоинт, пагинация, бірыңғай қате-модель, ретраи/таймауттар; TS+Python.
2. Scale (3-5 апта): Java/Go/.NET, WebhookVerifier, теңсіздік write, телеметрия hooks, OpenAPI модельдерін жасау.
3. Pro (үздіксіз): стриминг/SSE/gRPC, perf-оңтайландыру, LTS-тармақтары, кеңейтілген Cookbook, көші-қон/депрекация құралдары.

23) Шағын FAQ

Бәрін генерациялау керек пе, әлде қолмен жазу керек пе?
Модельдерді/клиенттерді жасаңыз, ал ergonomics (пагинаторлар, ретралар, іспеттілік, ыңғайлы белгілер) - қолмен.

Жеке async-SDK қажет пе?
В Python — да (`AsyncClient`); JS - әдепкі; в.NET/Java - мүмкіндігінше асинхронды қоңыраулар.

Тілдер тепе-теңдігін қалай сақтау керек?
CI-дегі матрица, «белдік бойынша» (TS → Py → Java → Go → .NET) автоматты репорты бар релиздер.

Жиынтығы

Күшті SDK - бұл бірыңғай бет, сенімді дефолттар және барлық тілдерде бірдей болжамды келісімшарттар. Әзірлеушілерге қауіпсіз «қорап» параметрлерін, түсінікті қате-модельді, ыңғайлы пагинацияны және веб-хуктерді тексеруді беріңіз, оны сапалы құжаттамамен және қатаң semver-пен аяқтаңыз. Сонда интеграция жылдам, қолдау арзан, ал экожүйе орнықты және ауқымды болады.