Тарроҳии SDK ва дастгирии забон

1) Ҳадафҳои SDK ва меъёрҳои муваффақият

Таҷрибаи таҳиякунанда (DX): API-ҳои интуитивӣ, семантикаи ягона байни забонҳо.
Эътимоднокӣ: танаффус/ақибнишинӣ/номутобиқатӣ аз қуттӣ.
Амният: асрҳо, имзоҳо, TLS, мутобиқат бо муҳитҳои proksi/企业.
Мушоҳида: гузоришҳо, ченакҳо, пайҳо дар абзорҳои стандартӣ барои забон.
Иқтисодиёт: ҳадди аққали egress/CPU, бутпарастии муассир, партияҳо.
Устуворӣ: нимкураи қатъӣ, мутобиқати қафо, филиалҳои LTS.

2) Принсипҳои меъморӣ

1. Мизоҷи лоғар, шартномаҳои қавӣ: парпечи SDK бар протокол (REST/GRPC), бидуни мантиқи пинҳонии тиҷорат.
2. Сатҳи ягона: мафҳумҳои якхела (Мизоҷ, Дархост, Ҷавоб, Хатогӣ, Пагинатор, WebhOOK Verifier).
3. Бехатар бо нобаёнӣ: танаффусҳои оқилона, ақибмонии экспоненсиалӣ + ҷиттер, муҳофизати такрорӣ.
4. Қабати конфигуратсия: ENV § config file constructor → параметрҳои метод.
5. Нақлиёти васлшаванда: HTTP/GRPC ҷудошаванда аст ва бо пайвастшавӣ мувофиқ аст proksi/池.
6. Санҷиш: интерфейс/қалбакӣ, тазриқи вобастагӣ, такрори сабт.
7. Хатогӣ I18n: machine 'error _ code' is устувор аст; паёмҳо локализатсияшавандаанд.

8. Дастрасӣ: вариантҳои асинхронӣ (одатан 'Async

9. Амният-аввал: дар ҳолати зарурӣ асрҳо ба гузоришҳо, нашри PII, китобхонаҳои криптографии FIPS мувофиқ нестанд.

3) Ҷадвали дастгирӣ ва баробарии имконият

Забон	Мини-версия	Модели иҷро	Платформаҳо/тақсимот	Статус
Намуди Скрипт/Java- Скрипт	Гиреҳи 18 +	async/интизор	npm (ESM + CJS), Deno, Bun	ГА
Python	3. 9+	синхронизатсия + aio	PYPI ('синхронизатсия '/' aio'), чархҳои manylinux	ГА
Ява	11+	синхронизатсия	Maven Марказӣ, Android (ихтиёрӣ)	ГА
Бирав	1. 21+	синхронизатсия (ctx)	Гузаштан ба модулҳо	ГА
.НЕТ	нет6. 0+	синхронизатсия/асинк	НУ Гет	ГА
PHP	8. 1+	синхронизатсия	Композитор	Бета
Руби	3. 0+	синхронизатсия	Руби Гемс	Бета

💡 Паритети API бо матритсаи автогенераторӣ чен карда мешавад: рӯйхати нуқта/хусусият, санаи баромад, "баробарӣ дорад? ».

4) Сатҳи пойгоҳи API (модели каноникӣ)

Субъектҳои умумӣ

Мизоҷ: танзими нақлиёт, калидҳо, ретрейҳо, қалмоқҳои телеметрӣ.
Дархост/Ҷавоб: моделҳои бехатар/DTO, pagination/cursors.
Хатогӣ: синфи ягона бо 'status', 'хатогӣ _ код', 'trace _ id', 'retriable'.
Пагинатор/Итератор: ҷустуҷӯи танбалии саҳифаҳо/курсорҳо.
Webhook .Verifier: Санҷиши HMAC/MTLS, тарҳ аз ҷониби 'event _ id'.

Намунаи хурд (Намуди скрипт)

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'.
Конструктор-Overrides ENV.
Бекор кардани ҳар як занг: таъхири сатҳи усул/бозсозӣ.
TLS/mTLS: роҳ ба сертификат/калид, ҳангоми зарурат пинҳон кардани CA.
Ҳавзҳои пайвастшавӣ: зинда мондан, HTTP/2, маҳдудияти мувофиқат.

6) Бехатарӣ аз қуттӣ

Асрори: сабт накунед, дар пайҳои анбора пинҳон кунед; сурх ".
Имзоҳо: HMAC барои webhooks, 'X-Key-Id '/гардиши калидҳо, дастгирии "ду калид" фаъол/оянда.
Идемпотенсия: танзими шаффофи амалиёти навиштани 'Idempotency-Key' for (бозоғоз бехатар аст).
RBAC/Соҳаҳо: ҳисобкунии мувофиқ/доимӣ барои миқёс.
Сиёсати PII: интерфейсҳои таҳриркунии стандартӣ барои сабти ном.

7) Эътимоднокӣ: Вақтсанҷӣ, ақибнишинӣ, пушт

Вақти пешфарз: 10-15 с; пайвастшавӣ 3-5s.
Retrai: барои 5xx/408/429 (эҳтиром 'Retry-After'), бозгашти экспоненсиалӣ + ҷиттер, маҳдудияти такрорӣ/вақт.
Пайвасткунак: ихтиёрӣ дар SDK (ё тавсияҳои тарафи сеюм).

Навиштани Idempotent: такрори худкор аз рӯи калид; бархӯрдҳо → баланд бардоштани '409. IDEMP_REPLAY'

8) Пагинатсия, курсорҳо ва ҷараён

Курсор/итератор: қувваи бераҳмонаи танбал, такрори худкор барои хатогиҳои муваққатӣ.
Саҳифабандии калидҳо: фармоиши устувор '(updated_at,id)'.
Backpressure: маҳдудияти дархостҳои ҳамзамон; v async-SDK - 'асинк барои '/' каналҳо'.

Сюзан (дар ҷое ки дастрас аст): SSE/Web

9) Хатогиҳо ва шартнома

Иерархияи ягона:

'Apibrul' (базовый) → подтипы: 'Auth' Хатогӣ (401) ',' Иҷозати хатогӣ (403) ',' Пайдо нашудааст (404) ',' Низоъ (409) ',' Меъёри лимит (429) ',' Хатогии тасдиқкунӣ (422) ',' Сервер Хатогӣ (5xx) '.
Свойства: 'статус', 'хатогӣ _ код', 'паём', 'trace _ id', 'интиқолшаванда', 'тафсилот'.
Таҷрибаи беҳтарин: паёмҳо аз ҷониби инсон хонда мешаванд, 'хатогӣ _ код' устувор аст.

10) Мафҳумҳои забон

Намуди Скрипт/JS

Ваъда + генераторҳо барои пагинатсия; Бастаҳои ESM + CJS.
Ларзиши дарахтон, полифилҳои ҳадди аққал, сигналҳои исқоти ҳамл ('Abort- Controller').

Python

Sync + Async (aiohttp/httpx), менеҷерони контекст, моделҳои 'пидантикӣ' (ё dataclasses).
Чархҳои dlya linux/macos/тирезаҳо; proxies/NO_PROXY дастгирӣ.

Java

'Анҷоми оянда' (агар лозим бошад), 'Auto' Closeable ',' Давомнокӣ ',' Иҷрокунанда '.
Мизоҷи HTTP: 'java. холис. http 'ё OKHttp; SLF4J барои гузоришҳо.

Бирав

Контексти контекстҳо. Контекст ',' http. Client 'with Transport, интерфейс барои санҷишҳо.
Хатои печондан ('fmt. Эррорф ("% w", хато) ', семантикаи хатоҳои sentinel.

.NET

'HttPclient', 'Бекоркунӣ', 'IA синхронизатсия <T>'.
Сиёсати полли (retry/circuit-breaker).

... ва ғайра барои PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) Воридшавӣ, ченакҳо, пайгирӣ

Гузоришҳо: сатҳҳо (ХАТО/WARN/INFO/DEBUG), таносуби 'trace _ id', хомӯш кардани маълумоти ҳассос.
Метрикӣ: 'дархостҳо _ total', 'хатогиҳо _ total {status}', 'retry _ count', 'latency _ ms', 'drottled _ total'.
Нишонаҳо: қалмоқҳои кушодаи Telemetry (ба занги API, нуқтаи ниҳоӣ, мақом, атрибутҳои такрорӣ).
Ҳолати ислоҳи хатоҳо: муҳити тағирёбандаи 'GH _ SDK _ DEBUG = 1' - чоп кардани сарлавҳаҳои HTTP (бе асрор) ва вақт.

12) Ҳуҷҷатгузорӣ ва намунаҳо

Quickstart 5 дақиқа: auth, дархости аввал, pagination, 429 коркард.
Cookbook: webhooks (санҷиши имзо), навиштани idempotent, такрори.
Маълумотномаи API: Autogen аз Open-API/Protobuf, аммо бо намунаҳои "дастӣ".
Порчаҳо: пораҳои омодашудаи код барои вазифаҳои маъмул (Python/TS/Java/Go/.NET).

13) Насл vs рамзгузории дастӣ

Равиши омехта: кодеген (моделҳо/мизоҷон) + дастӣ "қалам" барои эргономика/idempotency/paginators.
Қолибҳо: номҳои усули ягона ('эҷод/гирифтан/рӯйхат/навсозӣ/нест кардан'), stab. имзоҳо.
Санҷиши "мутобиқати дифф" пас аз regen (CI-дарвоза).

14) Версия, мутобиқат ва амортизатсия

Semver: X.Y.Z. Шикастан - танҳо асосӣ.
Сиёсати субот: Варақаҳои хурд - илова кардани майдонҳо/усулҳо, шартномаҳоро тағир намедиҳанд.
Амортизатсия: эзоҳҳо/атрибутҳо @ Deprecated/Кӯҳна, огоҳиҳои корӣ як маротиба дар як раванд, тиреза ≥ 90 рӯз.
Филиалҳои LTS: backport critfixes (хусусиятҳои нав надоранд).

15) Нашрияҳо ва занҷираи таъминот

CI/CD: линтерҳо/форматҳо, воҳиди + ҳамгироӣ, санҷишҳои шартномавӣ, e2e vs. sandbox.
Имзои Artifact: Sigstore/GPG, чекҳо дар релизҳо.

Нашр: npm/Py

Дарвозаи Sem-Ver: санҷиши худкори мутобиқати API-и ҷамъиятӣ (масалан, 'apiregistry diff').

16) Санҷиш (матритсаи сифат)

Воҳид: моделҳо, сериализатсия, санҷиш, бозсозӣ/танаффус.
Шартнома: бар зидди схемаҳои Open/API/Protobuf (ҳолатҳои манфӣ/канорӣ).
Интегратсия: против қуттии қуттӣ (idempotency, 429/5xx, webhooks).
Бор кардан/шустан: пагинатсия/ҷараён, backpressure.
Fuzz: майдонҳо/сарлавҳаҳо/ҳудуди вақт.
Compat - SDK-ҳои кӯҳна ↔ API-ҳои нав ва баръакс.
Бастаи дуд: 5 дақиқа барои ба даст овардани регрессия дар CI.

17) Сиёсати телеметрия ва махфият

Ихтиёрӣ-оптикӣ: ҷамъоварии ченакҳои ҷамъшудаи SDK (версия, забон, статус) бидуни PII.
Config: 'telemetry: хомӯш' беном 'пурра' (пешфарз хомӯш аст/беном аст).
Шаффофият: Ҳуҷҷате, ки чӣ рӯй медиҳад ва чаро; биёед қуттии пайвастшавиро тафтиш кунем.

18) Иҷро ва FIN

Бастабандӣ: якҷоя кардани дархостҳои хурд; маҳдуд RPS; gzip/br.
Caching ET/If-None-Match, шарти GET.
Моделҳои иқтисодӣ: итераторҳои танбал ба ҷои бор кардани ҳама чиз ба хотира.
Мувофиқат бо маҳдудият: 'max _ concurrency', то ба "DDOS" API.

19) Компонентҳои маъмулии SDK (скелетҳо)

Хатогӣ (Намуди Скрипт)

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

Веб-Верифиер (Гузаштан)

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 ва ҷомеа

SLA аз ҷониби SDK: иштибоҳҳои интиқодӣ - ислоҳи ETA, каналҳои иртиботӣ, матритсаи мутобиқат (SDK↔API).
Қолибҳои барориш: хатогӣ/хусусият/савол, худкори триаж аз рӯи забон/версия.
Харитаи роҳ/тамғакоғазҳо: "шумораи аввалини хуб", "кӯмак мехост".
Сиёсати амният: 'АМНИЯТ. md ', канал барои гузориш додани осебпазирӣ, дар ҳолати зарурӣ CVE.

21) Рӯйхати санҷиши сифати SDK

Хатои ягонаи модел ('ҳолат', 'хатогӣ _ код', 'trace _ id', 'retriable').
Вақтсанҷӣ/ақибнишинӣ/ҷиттер, эҳтиром ба 'Retry-After'.
Навиштани Idempotency, автоматии 'Idempotency-Key'.
Саҳифабандии курсор, итераторҳои танбал/ҷараёнҳо.
Webhook Verifier бо HMAC/MTLS ва deduplication.
Танзимот тавассути ENV/созанда/параметрҳо.
Вуруд/ченакҳо/OTel el қалмоқҳо, режими ислоҳи бидуни асрор.
Semver, камшавии 90 рӯз, филиалҳои LTS.
Мисолҳо ва китоби пухтупазро дар бораи вазифаҳои маъмул пур кунед.
Матритсаи мувозинати байни забонҳо дар CI.

22) Нақшаи амалисозӣ (3 такрорӣ)

1. MVP (2-3 ҳафта): Мизоҷи асосӣ, auth, 3-5 нуқтаи калидӣ, пагинатсия, модели ягонаи хатогӣ, ретрай/вақт; TS + Python.

2. Миқёс (3-5 ҳафта): Java/Go/.NET, WebhOOK Verifier, навиштани бесаводӣ, қалмоқҳои телеметрӣ, тавлидкунандаи моделҳо аз Open

3. Pro (муттасил): ҷараён/SSE/GRPC, оптимизатсияи perf, филиалҳои LTS, кукиҳои васеъ, воситаҳои муҳоҷират/декоратсия.

23) Мини-FAQ

Ҳама чизро тавлид кунед ё бо дасти худ нависед?
Тавлиди моделҳо/мизоҷон ва эргономика (пагинаторҳо, ретрейҳо, номутобиқатӣ, имзоҳои қулай) - дастӣ.

Оё ба ман async-SDK алоҳида лозим аст?
В Python - да ('Асинк Клиент'); дар JS - бо нобаёнӣ; v.NET/Java - агар имкон бошад, зангҳои асинхронӣ.

Чӣ тавр баробарии забонҳоро нигоҳ доштан мумкин аст?
Хусусияти матритса дар CI, "бо камарҳо" (TS → Py → Java → Go → .NET) бо гузориши худкор ", ки қафо мемонад" нашр мекунад.

Ҷамъ

SDK-и қавӣ як сатҳи ягона, пешфарзҳои боэътимод ва шартномаҳои пешгӯишаванда мебошанд, ки дар ҳама забонҳо якхелаанд. Ба таҳиягарон танзимоти бехатарро берун аз қуттӣ, модели хатогии фаҳмо, пагинги қулай ва санҷиши вебҳукҳо диҳед, инро бо ҳуҷҷатҳои баландсифат ва семвери қатъӣ пур кунед. Он гоҳ интегратсияҳо зуд, дастгирии арзон ва экосистема устувор ва миқёспазир хоҳанд буд.