Design SDK și suport lingvistic

1) Obiectivele SDK și criteriile de succes

Experiența dezvoltatorului (DX): API-uri intuitive, semantică uniformă între limbi.
Fiabilitate: timeout-uri/retrageri/idempotency din cutie.
Securitate: secrete, semnături, TLS, compatibilitate cu mediile proksi/企业.
Observabilitate: jurnale, valori, urme în instrumente standard pentru limbă.
Economie: ieșire minimă/procesor, paginare eficientă, loturi.
Stabilitate: semver strict, compatibilitate înapoi, ramuri LTS.

2) Principii arhitecturale

1. Client subțire, contracte puternice: înveliș SDK peste protocol (REST/gRPC), fără logică de afaceri ascunsă.
2. Suprafață unificată: aceleași concepte (Client, Cerere, Răspuns, Eroare, Paginator, WebhookVerifier).
3. Sigur în mod implicit: termene rezonabile, backoff exponențial + jitter, protecție repetiție.
4. Config stratificare: ENV → config fișier → constructor → parametrii metodei.
5. Transport conectabil: HTTP/gRPC este detașabil, compatibil cu proksi/池 de conectare.
6. Testabilitate: interfețe/falsuri, injecție de dependență, înregistrare-reluare.
7. Eroare I18n: machine 'error _ code' este stabil; mesajele sunt localizabile.
8. Accesibilitate: variante asincrone (de obicei „AsyncClient”), dacă este cazul.
9. Security-first: secretele nu se încadrează în jurnalele, ediția PII, bibliotecile cripto compatibile cu FIPS, dacă este necesar.

3) Tabelul de sprijin și paritatea oportunităților

Limbă	Mini-versiune	Model de execuție	Platforme/Distributie	Status
TypeScript/JavaScript	Nod 18 +	async/așteaptă	npm (ESM + CJS), Deno, Bun	GA
Python	3. 9+	sincronizare + aio	PyPI ('sincronizare '/' aio'), Roți manylinux	GA
Java	11+	sincronizare	Maven Central, Android (opțional)	GA
Du-te	1. 21+	sincronizare (ctx)	Module Go	GA
.NET	net6. 0+	sincronizare/async	NuGet	GA
PHP	8. 1+	sincronizare	Compozitor	Beta
Ruby	3. 0+	sincronizare	RubyGems	Beta

💡 Paritatea API este măsurată printr-o matrice autogenerată: lista/caracteristica punctului final, data lansării ", are paritate? ».

4) suprafață de bază API (model canonic)

Entități comune

Client: configurarea transportului, cheilor, retraielor, cârligelor de telemetrie.
Cerere/Răspuns: modele de tip-safe/DTO, paginare/cursoare.
Eroare: o singură clasă cu 'status', 'error _ code', 'trace _ id',' retriable '.
Paginator/Iterator: căutare leneș de pagini/cursoare.
WebhookVerificator: verificare HMAC/mTLS, dedup prin 'event _ id'.

Mini Exemplu (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-exemplu (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) Configurare și Runtime

ENV: 'GH _ API _ KEY', 'GH _ ENDPOINT', 'GH _ TIMEOUT _ MS',' HTTP _ PROXY/HTTPS _ PROXY ',' GH _ REGION '.
Constructor-Overrides ENV.
Suprascrie per apel: timeout/retray la nivel de metodă.
TLS/mTLS: calea către certificat/cheie, pinning CA, dacă este necesar.
Piscine de conexiune: păstrarea în viață, HTTP/2, constrângerea concurenței.

6) Siguranță din cutie

Secrete: nu vă conectați, ascundeți în urme de stivă; redactare ".
Semnături: HMAC pentru webhook-uri, 'X-Key-Id'/rotație cheie, suport pentru „două taste” activ/următor.
Idempotența: setarea transparentă a operațiunilor de scriere 'Idempotency-Key' (repornirea este sigură).
RBAC/Scopes: enumerări convenabile/constante pentru scopuri.
Politica PII: interfețe standard de editare pentru exploatarea forestieră.

7) Fiabilitate: Timeout, Retrageri, Spate

Timeout implicit: 10-15s; conexiune 3-5s.
Retrai: pentru 5xx/408/429 (respect 'Retry-After'), backoff exponențial + jitter, reîncercare/limită de timp.
Întrerupător de circuit: opțional în SDK (sau recomandări ale terților).

Scriere idempotentă: repetare automată după cheie; coliziuni → ridica '409. IDEMP_REPLAY'

8) Paginare, cursoare și streaming

Cursor/iterator: forță brută leneș, auto-repetă pentru erori tranzitorii.
Paginare Keyset: comandă stabilă „(updated_at,id)”.
Backpressure: limita cererilor simultane; в async-SDK - 'async pentru '/' canale'.
Streaming (acolo unde este disponibil): SSE/WebSocket/gRPC-stream cu auto-reconectare și eliminare a duplicatelor prin „secvență”.

9) Greșeli și contract

Ierarhie unică:

'ApiError' (базовый) → подтипы: 'AuthError (401)', 'PermissionError (403)', 'NotFound (404)', 'Conflict (409)', 'RateLimit (429)', 'ValidationError (422)', 'ServerErRor (5xx)'.
Свойства: 'status', 'error _ code', 'message', 'trace _ id',' retriable ',' details'.
Cele mai bune practici: mesajele pot fi citite de om, „error _ code” este stabil.

10) Idiomuri lingvistice

TypeScript/JS

Generatoare + pe bază de promisiune pentru paginare; Pachete ESM + CJS.
Tremuratul copacilor, polifileele minime, anularea semnalelor („AbortController”).

Python

Sincronizare + Async (aiohttp/httpx), manageri de context, modele 'pydantic' (sau dataclasses).
Roți для linux/macos/ferestre; Suport pentru proxies/NO_PROXY.

Java

'CompleteFuture' (dacă este necesar), 'AutoCloseable', 'Duration', 'Executor'.
Client HTTP: 'java. net. http 'sau OkHttp; SLF4J pentru buşteni.

Du-te

Contextul contextelor. Context „,” http. Client 'with tuned Transport, interfețe pentru teste.
Împachetarea erorilor ('fmt. Errorf ("% w", err) ", semantica santinelă a erorilor.

.NET

'HttpClientFactory', 'AnulareToken', 'IAsyncEnumerabil <T>'.
Politicile Polly (încercați din nou/circuit-breaker).

... etc. pentru PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) Logare, măsurători, urmărire

Jurnale: niveluri (ERROR/WARN/INFO/DEBUG), corelație "trace _ id', dezactivarea datelor sensibile.
Метрики: 'requests _ total', 'errors _ total {status}', 'retry _ count',' latency _ ms', 'throttled _ total'.
Urme: cârlige OpenTelemetry (durata apelului API, punctul final, starea, atributele de reîncercare).
Modul de depanare: variabila de mediu 'GH _ SDK _ DEBUG = 1' - imprimarea anteturilor HTTP (fără secrete) și ori.

12) Documentație și exemple

Quickstart 5 minute: auth, prima cerere, paginare, procesare 429.
Carte de bucate: cărți web (verificarea semnăturii), scriere idempotentă, reluare.
Referință API: Autogen de la OpenAPI/Protobuf, dar cu exemple „manuale”.
Fragmente: bucăți de cod gata făcute pentru sarcini populare (Python/TS/Java/Go/.NET).

13) Generare vs codificare manuală

Abordare combinată: codegen (modele/clienți) + „pixuri” manuale pentru ergonomie/idempotență/paginatori.
Șabloane: nume uniforme de metode ('create/get/list/update/delete'), înjunghiere. semnături.
Verificarea „diff-compatibilitate” după regen (CI-gate).

14) Versioning, compatibilitate și deprecieri

SemVer: X.Y.Z. Breaking - numai major.
Politica de stabilitate: versiuni minore - adăugați câmpuri/metode, nu modificați contractele.
Depreciere: adnotări/atribute @ Depreciate/învechite, avertismente de rulare o dată pe proces, fereastră ≥ 90 de zile.
Ramuri LTS: backport de critfixuri (fără caracteristici noi).

15) Lansări și lanț de aprovizionare

CI/CD: lintere/formatere, unitate + integrare, teste de contract, e2e vs. sandbox.
Semnătură artefact: Sigstore/GPG, sume de control pe versiuni.
Publicație: npm/PyPI/Maven/NuGet/Go/Compozitor/RubyGems cu changelog și note de lansare.
Poarta SemVer: verificarea automată a compatibilității API-ului public (de exemplu, „diff apiregistry”).

16) Testarea (matrice de calitate)

Unitate: modele, serializare, validare, retroys/timeout.
Contract: împotriva schemelor OpenAPI/Protobuf (cazuri negative/margine).
Integrare: vs. sandbox (idempotency, 429/5xx, webhooks).
Încărcare/înmuiere: paginare/flux, backpressure.
Fuzz: câmpuri/antete/limite de timp.
Compat - SDK-uri vechi ↔ API-uri noi și invers.
Pachet de fum: 5 minute pentru a prinde o regresie în CI.

17) Telemetrie și politici de confidențialitate

Opţional-opt-in: colecţie de valori SDK agregate (versiune, limbă, stări) fără PII.
Config: 'telemetrie: off' anonim 'full' (implicit este oprit/anonim).
Transparență: Documentați ce se va întâmpla și de ce; Să verificăm caseta de deconectare.

18) Performanță și FinOps

Batching: combina interogări mici; limita SPR; gzip/br.
ETag/If-None-Match caching, condiționat GET.
Modele economice: iteratori leneși în loc să încarce totul în memorie.
Concurență cu limită: 'max _ concurrency' pentru a nu „DDOS” API.

19) Componente SDK tipice (schelete)

Eroare (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

WebhookVerificator (Du-te)

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) Sprijin, SLA și comunitate

SLA by SDK: bug-uri critice - remediați ETA, canale de comunicare, matrice de compatibilitate (SDK↔API).
Șabloane de problemă: bug/caracteristică/întrebare, auto-triaj după limbă/versiune.
Foaie de parcurs/etichete: „bun primul număr”, „ajutor dorit”.
Politica de securitate: 'SECURITATE. md', canal pentru raportarea vulnerabilităților, CVE, dacă este necesar.

21) Lista de verificare a calității SDK

Eroare de model unic ('stare', 'error _ code', 'trace _ id',' recuperabil ').
Timeouts/retrageri/jitter, respect pentru 'Retry-After'.
Idempotency scrie, automat 'Idempotency-Key'.
Paginare cursor, iteratori leneși/fluxuri.
WebhookVerificator cu HMAC/mTLS și eliminarea duplicatelor.
Configurare prin ENV/constructor/parametri.
Logging/metrics/OTel cârlige, modul de depanare fără secrete.
SemVer, decretele de ≥90 zile, ramuri LTS.
Exemple complete și carte de bucate pe sarcini populare.
Caracteristică matrice de paritate între limbile din CI.

22) Planul de implementare (3 iterații)

1. MVP (2-3 săptămâni): Client de bază, auth, 3-5 puncte finale cheie, paginare, un singur model de eroare, retrai/timeout; TS + Python.
2. Scala (3-5 săptămâni): Java/Go/.NET, WebhookVerifier, scrierea idempotenței, cârlige de telemetrie, generarea de modele de la OpenAPI.
3. Pro (continuu): streaming/SSE/gRPC, optimizări perf, sucursale LTS, carte de bucate extinsă, instrumente de migrare/decrementare.

23) Mini-Întrebări frecvente

Să generezi totul sau să scrii cu mâinile?
Generați modele/clienți și ergonomie (paginatoare, retroactive, idempotență, semnături convenabile) - manual.

Am nevoie de un async-SDK separat?
В Python - да ('AsyncClient'); în JS - în mod implicit; v.NET/Java - apeluri asincrone, dacă este posibil.

Cum să păstrați paritatea limbilor?
Caracteristică matrice în CI, lansează „de curele” (TS→Py→Java→Go→.NET) cu auto-raport „care rămâne în urmă”.

Total

Un SDK puternic este o singură suprafață, implicite de încredere și contracte previzibile, care sunt aceleași în toate limbile. Oferiți dezvoltatorilor setări sigure din cutie, un model de eroare ușor de înțeles, paginare convenabilă și verificarea cărților web, completați acest lucru cu documentație de înaltă calitate și semver strict. Apoi, integrările vor fi rapide, sprijinul ieftin și ecosistemul durabil și scalabil.