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 транспорт: HTTP/gRPC өзгөрүлмө, Proxy/ байланыштар менен шайкеш келет.
6. Testability: Interfaces/жасалма, dependency injection, record-replay.
7. ката I18n: machine 'error _ code' туруктуу; билдирүүлөр локализацияланат.
8. Accessibility: асинхрондук параметрлери (адатта, 'AsyncClient') бул туура жерде.
9. Security-first: сырлар логиге түшпөйт, PII редакциясы, керек болсо FIPS шайкеш крипто китепчелери.

3) Колдоо таблицасы жана мүмкүнчүлүктөрдүн паритети

4) API негизги бети (канондук модели)

Жалпылыктар

Client: транспорт, ачкычтар, retrains, telemetry hooks.
Request/Response: типтүү коопсуз моделдер/DTO, pagination/курсор.
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: убакыт/методдун деъгээлинде retra.
TLS/mTLS: күбөлүк/ачкычка жол, зарыл болгон учурда CA pinning.
Байланыш пулдары: keep-alive, HTTP/2, параллелизмди чектөө.

6) кутудан коопсуздук

Сырлар: Логин жок, stack жолдорунда жашыруу; redaction ``.
Кол тамгалар: Вебхуктар үчүн HMAC, 'X-Key-Id '/ачкычтарды айлантуу, "эки ачкычты" колдоо active/next.
Демпотенттик: write-операциялар үчүн 'Idempotency-Key' тунук орнотуу (кайра баштоо коопсуз).
RBAC/Scopes: сатып алуу үчүн ыңгайлуу которуулар/туруктуу.
PII саясаты: стандарттык түзөтүү интерфейстери логин.

7) Ишенимдүүлүк: Таймауттар, ретрациялар, бэк-офф

демейки убакыт: 10-15s; 3-5с коннект.
Retrailer: 5xx/408/429 (урматтоо 'Retry-After'), экспоненциалдуу backoff + jitter, аракет/убакыт чеги.
Circuit-breaker: кошумча SDK (же үчүнчү тараптын либалар боюнча сунуштар).
Idempotent write: ачкыч боюнча автоматтык кайталоо; кагылышуулар → жогорулатуу '409 IDEMP_REPLAY'.

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

Курсор/итератор: жалкоо ашыкча, транзиенттик каталарда авто-кайталоо.
Keyset-pagination: туруктуу тартипке '(updated_at,id)'.
Backpressure: бир эле учурда суроо-талаптардын чеги; в async-SDK — `async for`/`channels`.
Агымы (жеткиликтүү жерде): SSE/WebSocket/gRPC-агымы менен auto-reconnect жана dedupe '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, минималдуу полифилдер, аборт сигналдары ('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, биринчи суроо, pagination, иштетүү 429.
Cookbook: Webhook (кол текшерүү), Empotent Write, реплика.
API колдонмо: OpenAPI/Protobuf тартып autogenes, бирок "кол" мисалдар менен.
Snippets: популярдуу тапшырмалар үчүн даяр код бөлүктөрү (Python/TS/Java/Go/.NET).

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

Айкалыштырылган ыкма: codegen (моделдер/кардарлар) + кол "туткалары" үчүн ergonomics/idempotentity/paginators.
Шаблондор: бирдиктүү ыкма аттары ('create/get/list/update/delete'), stab. белгилер.
Регенден кийин "diff-шайкештигин" текшерүү (CI-дарбазасы).

14) Версиялоо, шайкештик жана депрекация

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

15) Релиздер жана жеткирүү чынжыр

CI/CD: линтерлер/форматорлор, бирдик + интеграция, келишим-тесттер, e2e каршы кум.
Артефакттардын кол тамгасы: Sigstore/GPG, релиздерде checksums.
Post: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems менен changelog жана release notes.
SemVer gate: коомдук API шайкештигин auto-текшерүү (мисалы, 'apiregistry diff').

16) сыноо (сапат матрица)

Бирдик: моделдер, сериалдаштыруу, валидация, ретраи/таймауттар.
Contract: каршы OpenAPI/Protobuf схемалар (negative/edge cases).
Integration: каршы sandbox (idempotentity, 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.
Экономикалык моделдер: жалкоо итераторлор ордуна эс баарын жүктөп алуу.
чек менен параллелизм: 'max _ concurrency' эмес, "DDOSit" API.

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

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) колдоо, 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').
• Убакыт/Retry/Jitter, урматтоо 'Retry-After'.
• Idempotency write, автоматтык 'Idempotency-Key'.
• Pagination курсор, жалкоо итераторлор/агымдар.
• HMAC/mTLS жана дедуп менен WebhookVerifier.
• ENV/конструктор/параметрлери аркылуу конфигурация.
• Логин/метрика/OTel-Hook, сырлары жок Дебуг режими.
• SemVer, 90 күн ≥ депрекация, LTS бутактары.
• Популярдуу тапшырмалар боюнча толук мисалдар жана Cookbook.
• CI тилдеринин ортосундагы fich паритетинин матрицасы.

22) Ишке ашыруу планы (3 итерация)

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

23) Mini-FAQ

Баарын жаратабы же кол менен жазабы?
моделдерди/кардарларды түзүү, жана ergonomics (paginators, retrais, idempotentity, ыңгайлуу белгилери) - кол менен.

Өзүнчө async-SDK керекпи?
В Python — да (`AsyncClient`); JS - демейки; v.NET/Java - мүмкүн болушунча асинхрондук чалуулар.

Тилдин паритетин кантип сактоого болот?
CIдеги матрица, "кайыш боюнча" релиздери (TS → Py → Java → Go → .NET) "артта калган" авто-репорт менен.

Жыйынтык

Күчтүү SDK - бул бардык тилдерде бирдей бир бети, ишенимдүү демейки жана алдын ала келишимдер болуп саналат. Иштеп чыгуучуларга "кутудан" коопсуз орнотууларды, түшүнүктүү ката-моделди, ыңгайлуу пагинацияны жана вебхуктарды текшерүүнү берип, сапаттуу документтер жана катуу semver менен бүтүрүңүз. Ошондо интеграция тез болот, колдоо - арзан, ал эми экосистема - туруктуу жана масштабдуу.