Projekt SDK i wsparcie językowe

1) Cele SDK i kryteria sukcesu

Developer Experience (DX): intuicyjne interfejsy API, jednolite semantyki między językami.
Niezawodność: timeouts/retreats/idempotence out of the box.
Bezpieczeństwo: tajemnice, podpisy, TLS, kompatybilność z proksi/企业 środowiskami.
Obserwowalność: dzienniki, mierniki, ślady w standardowych narzędziach dla języka.
Gospodarka: minimalne wyjście/procesor, efektywna paginacja, partie.
Stabilność: ścisły semver, kompatybilność wsteczna, gałęzie LTS.

2) Zasady architektoniczne

1. Cienki klient, silne kontrakty: SDK wrapper over protocol (REST/gRPC), bez ukrytej logiki biznesowej.
2. Jednolita powierzchnia: te same koncepcje (klient, żądanie, odpowiedź, błąd, Paginator, WebhookVerifier).
3. Domyślnie bezpieczne: rozsądne czasy, wykładnicze backoff + jitter, ochrona przed powtarzaniem.
4. Warstwa konfiguracyjna: WG → plik config → konstruktor → parametry metody.
5. Transport wtykowy: HTTP/gRPC jest wymienny, kompatybilny z połączeniem proksi/odtwarzacz.
6. Testability: interfejsy/podróbki, wtrysk zależności, rekord-replay.
7. Błąd I18n: machine 'error _ code' jest stabilny; wiadomości są lokalizowane.
8. Dostępność: warianty asynchroniczne (zwykle „AsyncClient”) w stosownych przypadkach.
9. Security-first: sekrety nie wchodzą w rejestry, wydanie PII, biblioteki kryptograficzne kompatybilne z FIPS w razie potrzeby.

3) Wsparcie parytetu tabeli i okazji

4) powierzchnia bazowa API (model kanoniczny)

Wspólne podmioty

Klient: konfiguracja transportu, klucze, przekaźniki, haki telemetryczne.
Zapytanie/Odpowiedź: modele bezpieczne/DTO, paginacja/kursory.
Błąd: pojedyncza klasa z 'status', 'error _ code', 'trace _ id',' retriable '.
Paginator/Iterator: leniwe wyszukiwanie stron/kursorów.
WebhookVerifier: HMAC/mTLS check, dedup by 'event _ id'.

Mini Example (ΔScript)

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-przykład (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) Konfiguracja i czas trwania

•: 'GH _ API _ KEY', 'GH _ ENDPOINT', 'GH _ TIMEOUT _ MS', 'HTTP _ PROXY/HTTPS _ PROXY', 'GH _ REGION'.

Konstruktor-Nadjeżdża

Overrides per-call: timeout/retray na poziomie metody.
TLS/mTLS: ścieżka do certyfikatu/klucza, w razie potrzeby przypinanie urzędu certyfikacji.
Baseny połączeń: utrzymać przy życiu, HTTP/2, ograniczenia współistnienia.

6) Bezpieczeństwo poza pudełkiem

Sekrety: nie zaloguj się, ukryj ślady stosu; redakcja ".
Podpisy: HMAC dla webhooks, 'X-Key-Id'/key rotation, wsparcie dla' two keys 'active/next.
Idempotencja: przejrzyste ustawienie 'Idempotence-Key' dla operacji zapisu (ponowne uruchomienie jest bezpieczne).
RBAC/Scopes: wygodne numery/stałe dla zakresów.
Polityka PII: standardowe interfejsy edycji do rejestrowania.

7) Niezawodność: Timeouts, Retreats, Backs

Domyślny czas: 10-15s; połączenie 3-5s.
Retrai: dla 5xx/408/429 (szacunek 'Retry-After'), wykładniczy backoff + jitter, termin retry/time.
Wyłącznik-wyłącznik: opcjonalny w SDK (lub zalecenia osób trzecich).

Idempotent write: automatyczne powtarzanie przez klucz; kolizje → podnieść '409. IDEMP_REPLAY'

8) Paginacja, kursory i strumieniowe

Kursor/iterator: leniwa siła brutalna, automatyczne powtarzanie błędów przejściowych.
Paginacja keyset: stabilne zamawianie '(updated_at,id)'.
Backpressure: limit jednoczesnych żądań; мasync-SDK - 'async dla '/' kanałów'.
Streaming (o ile jest dostępny): SSE/WebSocket/gRPC-stream z automatycznym ponownym połączeniem i deduplikacją przez „sekwencję”.

9) Błędy i umowa

• „ApiError” (бабова) → бодтива: „AuthError (401)”, „PerError (403)”, „Nota znaleziona (404)”, „Konflikt (409)”, „Na granicy (429)”, „WalidacjError (422)”, „ServerError (5xx)”.
• Своства: 'status', 'error _ code', 'message', 'trace _ id',' retriable ',' details '.
• Najlepsza praktyka: wiadomości są czytelne dla ludzi, „error _ code” jest stabilny.

10) Idioms językowe

Skrypt/JS

Generatory obietnic + dla paginacji; Pakiety ESM + CJS.
Trzęsące się drzewa, minimalne polifile, sygnały przerywania ciąży („AbortController”).

Python

Synchronizator + async (aiohttp/httpx), menedżery kontekstowe, modele „pydantyczne” (lub lasery danych).
Koła дла linux/macos/windows; Wsparcie proxies/NO_PROXY.

Java

„ Future” (w razie potrzeby), „AutoCloseable”, „Duration”, „Executor”.
Klient HTTP: 'java. netto. http 'lub OkHttp; SLF4J do dzienników.

Idź

Kontekst kontekstu. Kontekst „,” http. Klient 'z tuned Transport, interfejsy do testów.
Pakowanie błędów ('fmt. Błąd („% w”, err) '), semantyka wskaźnikowa błędów.

.NET

' ClientFactory', 'CancellationToken', 'IASyncEnumerable <T>'.
Polly policies (retry/circuit-breaker).

... itp. dla PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) Wyrąb, mierniki, odwzorowanie

Dzienniki: poziomy (ERROR/WARN/INFO/DEBUG), korelacja 'trace _ id', wyłączanie danych wrażliwych.
Метрика: 'requests _ total', 'errors _ total {status}', 'retry _ count',' latency _ ms ',' throttled _ total '.
Traces: OpenTelemetry haki (rozpiętość do wywołania API, punkt końcowy, status, atrybuty retry).
Tryb debugowania: zmienna środowiskowa 'GH _ SDK _ DEBUG = 1' - drukowanie nagłówków HTTP (bez tajemnic) i czasów.

12) Dokumentacja i przykłady

Szybkie uruchomienie 5 minut: auth, pierwsze żądanie, paginacja, przetwarzanie 429.
Książka kucharska: haki internetowe (weryfikacja podpisu), idempotent napisać, powtórzyć.
Odniesienie API: Autogen z OpenAPI/Protobuf, ale z przykładami „ręcznymi”.
Snippets: gotowe kawałki kodu dla popularnych zadań (Python/TS/Java/Go/.NET).

13) Generacja vs ręczny kodowanie

Podejście połączone: kodegen (modele/klienci) + ręczne „długopisy” dla ergonomii/idempotencji/paginatorów.
Szablony: jednolite nazwy metod ('create/get/list/update/delete'), stab. podpisy.
Sprawdzanie „dyflikacji” po regenie (CI-gate).

14) Wersioning, kompatybilność i depresje

SemVer: X.Y.Z. Breaking - tylko major.
Polityka stabilności: drobne wydania - dodawanie pól/metod, nie zmienianie umów.
Deprecation: adnotacje/atrybuty @ Deprecated/Obsolete, ostrzeżenia runtime raz na proces, okno ≥ 90 dni.
Gałęzie LTS: backport krytyki (brak nowych funkcji).

15) Wydania i łańcucha dostaw

CI/CD: linters/formatters, unit + integration, contract tests, e2e vs. sandbox.
Podpis artefaktowy: Sigstore/GPG, czeki na wydania.
Publikacja: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems with changelog and release notes.
Brama SemVer: automatyczne sprawdzanie zgodności publicznego API (na przykład „apiregistry diff”).

16) Badanie (matryca jakości)

Jednostka: modele, serializacja, walidacja, przekłady/timeouts.
Kontrakt: przeciwko systemom OpenAPI/Protobuf (przypadki negatywne/krawędziowe).
Integracja: kontra piaskownica (idempotencja, 429/5xx, haki internetowe).
Obciążenie/moczenie: paginacja/strumień, ciśnienie wsteczne.
Fuzz: pola/nagłówki/granice czasowe.
Compat - stare SDKs i na odwrót nowe API.
Opakowanie dymne: 5 minut, aby złapać regresję w CI.

17) Polityka telemetrii i prywatności

Opcjonalnie opt-in: zbiór zagregowanych mierników SDK (wersja, język, statusy) bez PII.
Config: 'telemetry: off' anonimowy 'full' (domyślnie jest wyłączony/anonimowy).
Przejrzystość: Udokumentuj, co się stanie i dlaczego; Sprawdźmy pole odłączenia.

18) Wydajność i FinOp

Dozowanie: połączyć małe zapytania; limit RPS; gzip/br.
ETag/If-None-Match buforowanie, warunkowe GET.
Ekonomiczne modele: leniwe iteratory zamiast ładować wszystko do pamięci.
Równoczesność z limitem: 'max _ concurrency', aby nie „DDOS” API.

19) Typowe elementy SDK (szkielety)

Błąd (ΔScript)

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) Wsparcie, SLA i Wspólnota

SLA przez SDK: błędy krytyczne - naprawić ETA, kanały komunikacyjne, matryca kompatybilności (SDK i API).
Szablony emisji: błąd/funkcja/pytanie, auto-triage według języka/wersji.
Plan działania/etykiety: „dobry pierwszy numer”, „pomoc”.
Polityka bezpieczeństwa: "BEZPIECZEŃSTWO. md', kanał zgłaszania luk, w razie potrzeby CVE.

21) Lista kontrolna jakości SDK

• Błąd jednego modelu ("status", "error _ code", "trace _ id'," retriable ").
• Timeouts/retreats/jitter, szacunek dla 'Retry-After'.
• Idempotence write, automatyczne 'Idempotence-Key'.
• Paginacja kursora, leniwe iteratory/strumienie.
• WebhookVerifier z HMAC/mTLS i deduplication.
• Konfiguracja za pomocą parametrów/konstruktora.
• Logowanie/metryki/haki OTel, tryb debugowania bez tajemnic.
• SemVer, zmniejszenie o ≥ 90 dni, oddziały LTS.
• Kompletne przykłady i Książka kucharska na popularnych zadań.
• Macierz parytetu funkcji między językami w CI.

22) Plan realizacji (3 iteracje)

1. MVP (2-3 tygodnie): podstawowy klient, auth, 3-5 kluczowych punktów końcowych, paginacja, pojedynczy model błędu, retrai/timeouts; TS + Python.
2. Skala (3-5 tygodni): Java/Go/.NET, WebhookVerifier, pisanie idempotencji, haki telemetryczne, generowanie modeli z OpenAPI.
3. Pro (continuous): streaming/SSE/gRPC, optymalizacja perf, oddziały LTS, rozszerzona książka kucharska, narzędzia migracji/redukcji.

23) Mini-FAQ

Generować wszystko czy pisać rękami?
Generowanie modeli/klientów i ergonomii (paginatory, przekładki, idempotencja, wygodne podpisy) - ręcznie.

Czy potrzebuję osobnego async-SDK?
МаТРА („AsyncClient”); w JS - domyślnie; v.NET/Java - rozmowy asynchroniczne, jeśli to możliwe.

Jak zachować parytet języków?
Matrix funkcja w CI, wydania „przez pasy” (TS → Py → Java → Go → .NET) z auto-raport „, że pozostaje za”.

Razem

Silny SDK to pojedyncza powierzchnia, niezawodne domyślne i przewidywalne umowy, które są takie same we wszystkich językach. Daj programistom bezpieczne ustawienia poza pudełkiem, zrozumiały model błędu, wygodną paginację i weryfikację haków webowych, uzupełnij to o wysokiej jakości dokumentację i ścisły semver. Wtedy integracje będą szybkie, wsparcie tanie, a ekosystem zrównoważony i skalowalny.