SDK tasarım ve dil desteği

1) SDK hedefleri ve başarı kriterleri

Geliştirici Deneyimi (DX): sezgisel API'ler, diller arasında tek tip semantik.
Güvenilirlik: Zaman aşımları/geri çekilmeler/idempotency kutudan çıkar.
Güvenlik: sırlar, imzalar, TLS, proksi/企业 ortamlarla uyumluluk.
Gözlemlenebilirlik: günlükler, metrikler, dil için standart araçlardaki izler.
Ekonomi: minimum çıkış/CPU, etkili sayfalama, partiler.
Kararlılık: sıkı semver, geriye dönük uyumluluk, LTS dalları.

2) Mimari ilkeler

1. İnce istemci, güçlü sözleşmeler: Gizli iş mantığı olmadan protokol üzerinde SDK sarıcı (REST/gRPC).
2. Birleştirilmiş yüzey: aynı kavramlar (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Varsayılan olarak güvenli: makul zaman aşımları, üstel geri çekilme + titreme, tekrarlama koruması.
4. Yapılandırma katmanlaması: ENV - yapılandırma dosyası - yapıcı - yöntem parametreleri.
5. Takılabilir taşıma: HTTP/gRPC çıkarılabilir, bağlantı proksi/池 ile uyumludur.
6. Test edilebilirlik: arayüzler/sahte, bağımlılık enjeksiyonu, kayıt tekrarı.
7. Hata I18n: machine 'error _ code' kararlı; Mesajlar yerelleştirilebilir.
8. Erişilebilirlik: Uygun olduğunda asenkron varyantlar (genellikle 'AsyncClient').
9. Önce güvenlik: sırlar günlüklere, PII sürümüne, gerekirse FIPS uyumlu kripto kütüphanelerine girmez.

3) Destek tablosu ve fırsat paritesi

4) API taban yüzeyi (kanonik model)

Ortak varlıklar

İstemci: taşıma, tuşlar, retray, telemetri kancaları yapılandırılıyor.
İstek/Yanıt: tip güvenli modeller/DTO, sayfalama/imleçler.
Hata: 'status', 'error _ code', 'trace _ id', 'receivable' içeren tek bir sınıf.
Paginator/Iterator: Sayfaların/imleçlerin tembel araması.
WebhookDoğrulayıcı: HMAC/mTLS kontrolü, 'event _ id'ile dedup.

Mini Örnek (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-örnek (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) Yapılandırma ve Çalışma Süresi

ENV: 'GH _ API _ KEY', 'GH _ ENDPOINT', 'GH _ TIMEOUT _ MS', 'HTTP _ PROXY/HTTPS _ PROXY', 'GH _ REGION'.
Constructor-Overrides ENV.
Çağrı başına geçersiz kılmalar: yöntem düzeyinde zaman aşımı/yeniden ödeme.
TLS/mTLS: sertifika/anahtar yolu, gerekirse CA sabitleme.
Bağlantı havuzları: canlı tutma, HTTP/2, eşzamanlılık kısıtlaması.

6) Kutudan çıkan güvenlik

Sırlar: kayıt yapmayın, yığın izlerine gizleyin; redaksiyon ".
İmzalar: Webhooks için HMAC, 'X-Key-Id'/tuş döndürme, "iki anahtar" için destek etkin/sonraki.
Idempotency: yazma işlemleri için şeffaf 'Idempotency-Key' ayarı (yeniden başlatma güvenlidir).
RBAC/Scopes: kapsamlar için uygun numaralandırmalar/sabitler.
PII politikası: Günlük kaydı için standart düzenleme arayüzleri.

7) Güvenilirlik: Zaman aşımları, geri çekilmeler, Sırtlar

Varsayılan zaman aşımı: 10-15s; Bağlantı 3-5'ler.
Retrai: 5xx/408/429 için ('Retry-After'a saygı gösterin), üstel geri dönüş + jitter, yeniden deneme/zaman sınırı.
Devre kesici: SDK'da isteğe bağlı (veya üçüncü taraf lib önerileri).

Idempotent yazma: anahtarla otomatik tekrarlama; Çarpışmalar "409'u yükseltir. IDEMP_REPLAY'

8) Pagination, imleçler ve akış

İmleç/yineleyici: tembel kaba kuvvet, geçici hatalar için otomatik tekrarlar.
Keyset sayfalama: kararlı sipariş '(updated_at,id)'.
Backpressure: eşzamanlı isteklerin sınırı; в async-SDK - 'async for'/' kanallar'.
Akış (varsa): SSE/WebSocket/gRPC-stream, otomatik yeniden bağlanma ve 'sıra'ile veri tekilleştirme.

9) Hatalar ve sözleşme

• 'ApiError' (базовый) - подтипы: 'AuthError (401)', 'PermissionError (403)', 'NotFound (404)', 'Conflict (409)', 'RateLimit (429)', 'ValidationError (422)', 'ServerError (5xx)'.
• Свойства: 'status', 'error _ code', 'message', 'trace _ id', 'receivable', 'details'.
• En iyi uygulama: mesajlar insan tarafından okunabilir, 'error _ code' kararlı.

10) Dil deyimleri

TypeScript/JS

Sayfalama için Promise tabanlı + jeneratörler; ESM + CJS paketleri.
Ağaç sallama, minimal polifiller, iptal sinyalleri ('AbortController').

Python

Sync + Async (aiohttp/httpx), bağlam yöneticileri, 'pydantic' modelleri (veya veri sınıfları).
Tekerlekler для linux/macos/pencereler; proxies/NO_PROXY desteği.

Java

'CompleteFuture' (gerekirse), 'AutoCloseable', 'Duration', 'Executor'.
HTTP istemcisi: 'java. Net. http 'veya OkHttp; Günlükler için SLF4J.

Git

Bağlam bağlamı. Bağlam ', http. Client 'ayarlı Transport, testler için arayüzler.
Sarma hatası ('fmt. Errorf ("% w", err) '), hataların sentinel anlambilimi.

.NET

'HttpClientFactory', 'CancellationToken', 'IAsyncEnumerable <T>'.
Polly politikaları (yeniden deneme/devre kesici).

... Vb PHP/Ruby için (PSR-18, Faraday/Net:: HTTP).

11) Günlük kaydı, metrikler, izleme

Günlükler: düzeyler (ERROR/WARN/INFO/DEBUG), korelasyon 'trace _ id', hassas verileri devre dışı bırakma.
Метрики: 'requests _ total', 'errors _ total {status}', 'retry _ count', 'latency _ ms', 'throttled _ total'.
İzler: OpenTelemetry kancaları (API çağrısına yayılma, uç nokta, durum, yeniden deneme nitelikleri).
Debug modu: ortam değişkeni 'GH _ SDK _ DEBUG = 1' - HTTP başlıklarını (sırsız) ve zamanları yazdırma.

12) Belgeler ve örnekler

Hızlı başlangıç 5 dakika: auth, ilk istek, pagination, 429 işleme.
Yemek kitabı: webhooks (imza doğrulama), idempotent yazma, yeniden oynatma.
API referansı: OpenAPI/Protobuf'tan Autogen, ancak "manuel" örneklerle.
Snippet'ler: Popüler görevler için hazır kod parçaları (Python/TS/Java/Go/.NET).

13) Nesil vs manuel kodlama

Kombine yaklaşım: codegen (modeller/istemciler) + ergonomi/idempotency/paginators için manuel "kalemler".
Şablonlar: tek tip yöntem adları ('oluştur/al/listele/güncelle/sil'), saplama. İmzalar.
Regen'den (CI-gate) sonra "diff-uyumluluğu" kontrol ediliyor.

14) Sürüm oluşturma, uyumluluk ve amortismanlar

SemVer: X.Y.Z. Breaking - sadece majör.
İstikrar politikası: küçük sürümler - alanlar/yöntemler ekleyin, sözleşmeleri değiştirmeyin.
Kullanımdan kaldırma: ek açıklamalar/nitelikler @ Kullanımdan kaldırılmış/Eski, işlem başına bir kez çalışma zamanı uyarıları, 90 gün ≥ pencere.
LTS dalları: critfixlerin arka portu (yeni özellik yok).

15) Bültenler ve Tedarik Zinciri

CI/CD: linters/formatters, unit + integration, contract tests, e2e vs. Sandbox.
Artifact imzası: Sigstore/GPG, sürümlerde checksums.
Yayın: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems with changelog and release notes.
SemVer kapısı: Genel API'nin uyumluluğunu otomatik olarak kontrol etme (örneğin, 'apiregistry diff').

16) Test etme (kalite matrisi)

Birim: modeller, serileştirme, doğrulama, geri alma/zaman aşımları.
Sözleşme: OpenAPI/Protobuf şemalarına karşı (negatif/uç durumlar).
Entegrasyon: Sandbox'a karşı (idempotency, 429/5xx, webhooks).
Load/soak: pagination/stream, backpressure.
Fuzz: alanlar/başlıklar/zaman sınırları.
Compat - eski SDK'lar yeni API'ler ↔ ve bunun tersi de geçerlidir.
Duman paketi: CI'da bir gerileme yakalamak için 5 dakika.

17) Telemetri ve gizlilik politikaları

İsteğe bağlı-opt-in: PII içermeyen toplu SDK metrikleri (sürüm, dil, durumlar) koleksiyonu.
Yapılandırma: 'telemetri: kapalı' anonim 'tam' (varsayılan kapalı/anonim).
Şeffaflık: Ne olacağını ve nedenini belgeleyin; Bağlantı kesme kutusunu kontrol edelim.

18) Performans ve FinOps

Gruplama: küçük sorguları birleştirin; Limit RPS; gzip/br.
ETag/If-None-Match önbelleğe alma, koşullu GET.
Ekonomik modeller: Her şeyi belleğe yüklemek yerine tembel yineleyiciler.
Limit ile eşzamanlılık: API'yi "DDOS" yapmamak için 'max _ concurrency'.

19) Tipik SDK bileşenleri (iskeletler)

Hata (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 (Git)

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) Destek, SLA ve Topluluk

SLA by SDK: kritik hatalar - ETA'yı, iletişim kanallarını, uyumluluk matrisini (SDK↔API) düzeltin.
Sorun şablonları: hata/özellik/soru, dile/sürüme göre otomatik triyaj.
Yol haritası/etiketler:'ilk iyi konu "," yardım aranıyor ".
Güvenlik politikası: "GÜVENLİK. md ', güvenlik açıklarını bildirmek için kanal, gerekirse CVE.

21) SDK Kalite Kontrol Listesi

• Tek model hatası ('durum', 'error _ code', 'trace _ id', 'yeniden kullanılabilir').
• Zaman aşımları/geri çekilmeler/jitter, 'Retry-After' için saygı.
• Idempotency yazma, otomatik 'Idempotency-Key'.
• İmleç sayfalama, tembel yineleyiciler/akışlar.
• HMAC/mTLS ve veri tekilleştirme ile WebhookDoğrulayıcı.
• ENV/yapıcı/parametreler aracılığıyla yapılandırma.
• Günlük kaydı/metrikler/OTel kancaları, sırsız hata ayıklama modu.
• SemVer, ≥90 günlük indirimler, LTS şubeleri.
• Popüler görevler hakkında eksiksiz örnekler ve Yemek Kitabı.
• CI'daki diller arasında özellik eşlik matrisi.

22) Uygulama planı (3 yineleme)

1. MVP (2-3 hafta): temel istemci, auth, 3-5 anahtar bitiş noktası, sayfalama, tek hata modeli, retrai/zaman aşımları; TS + Python.
2. Ölçek (3-5 hafta): Java/Go/.NET, WebhookVerifier, idempotency yazma, telemetri kancaları, OpenAPI'dan modeller üretme.
3. Pro (sürekli): akış/SSE/gRPC, perf optimizasyonları, LTS dalları, genişletilmiş Yemek Kitabı, geçiş/azaltma araçları.

23) Mini-SSS

Her şeyi üretmek veya ellerinizle yazmak?
Modeller/istemciler ve ergonomi (sayfalayıcılar, retrays, idempotency, uygun imzalar) oluşturun - manuel olarak.

Ayrı bir async-SDK'ya ihtiyacım var mı?
В Python - да ('AsyncClient'); JS'de - varsayılan olarak; V.NET/Java - mümkünse asenkron aramalar.

Dillerin eşitliği nasıl sağlanır?
CI'daki Matrix özelliği, "kayışlara göre" (TS, Py, Java, Go, .NET) "geride kalan" otomatik raporla serbest bırakır.

Toplam

Güçlü bir SDK, tüm dillerde aynı olan tek bir yüzey, güvenilir varsayılanlar ve öngörülebilir sözleşmelerdir. Geliştiricilere kutudan güvenli ayarlar, anlaşılabilir bir hata modeli, uygun sayfalama ve web kitaplarının doğrulanmasını sağlayın, bunu yüksek kaliteli belgeler ve katı semver ile tamamlayın. Daha sonra entegrasyonlar hızlı, destek ucuz ve ekosistem sürdürülebilir ve ölçeklenebilir olacaktır.