طراحی SDK و پشتیبانی از زبان

1) اهداف SDK و معیارهای موفقیت

تجربه توسعه دهنده (DX): API های بصری، معانی یکنواخت بین زبان ها.
قابلیت اطمینان: زمان بندی/عقب نشینی/idempotency از جعبه.
امنیت: اسرار، امضا، TLS، سازگاری با محیط های proksi/企业.
قابلیت مشاهده: سیاهههای مربوط، معیارها، ردیابی در ابزارهای استاندارد برای زبان.
اقتصاد: حداقل خروج/CPU، صفحه بندی موثر، دسته ها.
پایداری: سمور سخت، سازگاری عقب، شاخه های LTS.

2) اصول معماری

1. مشتری نازک، قراردادهای قوی: بسته بندی SDK بر روی پروتکل (REST/gRPC)، بدون منطق کسب و کار پنهان.
2. سطح یکپارچه: مفاهیم مشابه (مشتری، درخواست، پاسخ، خطا، Paginator، WebhookVerifier).
3. ایمن به طور پیش فرض: زمان معقول، عقب نشینی نمایشی + jitter، حفاظت از تکرار.
4. لایه بندی پیکربندی: ENV → فایل پیکربندی → پارامترهای سازنده → روش.
5. حمل و نقل قابل حمل: HTTP/gRPC قابل جابجایی است، سازگار با proksi/池 اتصال.
6. تست پذیری: رابط/جعلی، تزریق وابستگی، پخش مجدد ضبط.
7. I18n خطا: machine 'error _ code' is stable ؛ پیامها محلی هستند.
8. قابلیت دسترسی: انواع آسنکرون (معمولا «AsyncClient») در صورت لزوم.
9. امنیت اول: اسرار به سیاهههای مربوط نمی افتد, نسخه PII, کتابخانه رمزنگاری FIPS سازگار در صورت لزوم.

3) جدول پشتیبانی و برابری فرصت

4) سطح پایه API (مدل متعارف)

نهادهای مشترک

مشتری: پیکربندی حمل و نقل، کلید، retrays، قلاب تله متری.
درخواست/پاسخ: مدل های نوع ایمن/DTO، صفحه بندی/نشانگر.
خطا: یک کلاس منفرد با 'status', 'error _ code', 'trace _ id', 'retriable'.
Paginator/Iterator: جستجوی تنبل صفحات/نمایشگرها.
WebhookVerifier: بررسی HMAC/mTLS، dedup توسط «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 })) { /... / }

مینی مثال (پایتون، 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.
لغو هر فراخوانی: timeout/retray سطح روش.
TLS/mTLS: مسیر به گواهی/کلید، پین کردن CA در صورت لزوم.
استخرهای اتصال: زنده نگه داشتن، HTTP/2، محدودیت همزمان.

6) ایمنی خارج از جعبه

اسرار: وارد نشوید، در ردیابی پشته پنهان شوید. اصلاح ".
امضاها: HMAC برای webhooks، 'X-Key-Id '/چرخش کلید، پشتیبانی از «دو کلید» فعال/بعدی.
Idempotency: تنظیم شفاف عملیات نوشتن «Idempotency-Key» (راه اندازی مجدد ایمن است).
RBAC/حوزه: enumerations مناسب/ثابت برای حوزه.
سیاست PII: رابط های ویرایش استاندارد برای ورود به سیستم.

7) قابلیت اطمینان: زمان، عقب نشینی، پشت

اتمام وقت پیش فرض: 10-15 ثانیه ؛ اتصال 3-5 ثانیه

Retrai: برای 5xx/408/429 (احترام 'Retry-After')، عقب نشینی نمایشی + لرزش، محدودیت مجدد/زمان.
قطع کننده مدار: اختیاری در SDK (یا توصیه های شخص ثالث).

نوشتن Idempotent: تکرار خودکار با کلید ؛ افزایش 409. IDEMP_REPLAY'

8) صفحه بندی، نشانگر و جریان

مکان نما/تکرار کننده: نیروی بی رحم تنبل، تکرار خودکار برای خطاهای گذرا.
صفحهبندی صفحه کلید: ترتیب پایدار '(updated_at,id)'.
فشار پشتی: محدودیت درخواست همزمان ؛ в async-SDK - 'async برای '/' کانال'.
جریان (در صورت وجود): SSE/WebSocket/gRPC-جریان با خودکار اتصال مجدد و deduplication توسط 'دنباله'.

9) اشتباهات و قرارداد

• 'ApiError' (базовый) → подтипы: 'AuthError (401)', 'PermissionError (403)', 'NotFound (404)', 'Conflict (409)', 'RateLimit (429)', 'ValidationError (422)', 'ServerError (5xx)'.
• Свойства: «وضعیت»، «خطا _ کد»، «پیام»، «ردیابی _ id»، «قابل بازیابی»، «جزئیات».
• بهترین روش: پیام ها قابل خواندن توسط انسان هستند، «error _ code» پایدار است.

10) اصطلاحات زبان

نوع اسکریپت/JS

ژنراتورهای + مبتنی بر وعده برای صفحه بندی ؛ بسته های ESM + CJS

لرزش درخت، پلیفیلهای حداقل، سیگنالهای سقط جنین ('AbortController').

پایتون

Sync + Async (aiohttp/httpx)، مدیران زمینه، مدلهای «pydantic» (یا dataclasses).

چرخ для لینوکس/macos/ویندوز ؛ پشتیبانی proxies/NO_PROXY

جاوا

'CompleteFuture' (در صورت لزوم)، 'AutoCloseable'، 'Duration'، 'Executor'.

مشتری HTTP: "جاوا. شبکه. http یا OkHttp ؛ SLF4J برای لاگ ها

برو

زمینه زمینه. متن '،' HTTP. مشتری با حمل و نقل تنظیم شده، رابط برای تست.
بسته بندی خطا ('fmt. Errorf ("% w", err) "), sentinel semantics of errors.

.NET

'HttpClientFactory'، 'CancellationToken'، 'IAsyncEnumerable <T>'.
سیاست های پولی (سعی مجدد/قطع کننده مدار).

... و غیره برای 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 (به تماس API، نقطه پایانی، وضعیت، ویژگی های مجدد).
حالت اشکال زدایی: متغیر محیطی 'GH _ SDK _ DEBUG = 1' - چاپ هدر HTTP (بدون اسرار) و زمان.

12) مستندات و نمونه ها

شروع سریع 5 دقیقه: auth، درخواست اول، صفحه بندی، پردازش 429.
کتاب آشپزی: webhooks (تایید امضا)، نوشتن idempotent، پخش.
مرجع API: Autogen از OpenAPI/Protobuf، اما با نمونه های «دستی».
Snippets: قطعه کد آماده برای کارهای محبوب (Python/TS/Java/Go/.NET).

13) نسل در مقابل برنامه نویسی دستی

رویکرد ترکیبی: codegen (مدل/مشتری) + «قلم» دستی برای ارگونومی/idempotency/paginators.

قالب ها: نام متدهای یکنواخت ('create/get/list/update/delete'), stab. امضا ها

چک کردن «diff-compatibility» پس از regen (CI-gate).

14) نسخه، سازگاری و تخفیف

SemVer: X.Y.Z شکستن - تنها عمده.
سیاست پایداری: نسخه های جزئی - اضافه کردن زمینه ها/روش ها، قراردادها را تغییر ندهید.
تخفیف: حاشیه نویسی/ویژگی های @ منسوخ/منسوخ، هشدارهای زمان اجرا یک بار در هر فرآیند، پنجره ≥ 90 روز.
شاخه های LTS: backport از critifixes (بدون ویژگی های جدید).

15) انتشار و زنجیره تامین

CI/CD: لاینترها/قالب ها، واحد + ادغام، تست قرارداد، e2e در مقابل sandbox.
امضای مصنوعی: Sigstore/GPG، چک سام در نسخه.
انتشار: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems با تغییرات و یادداشت های انتشار.
دروازه SemVer: خودکار بررسی سازگاری API عمومی (به عنوان مثال، 'تفاوت apiregistry').

16) تست (ماتریس کیفیت)

واحد: مدل ها، سریال سازی، اعتبار سنجی، بازپرداخت/زمان بندی.
قرارداد: در برابر طرحهای OpenAPI/Protobuf (موارد منفی/لبه).
ادغام: در مقابل sandbox (idempotency، 429/5xx، webhooks).
بار/خیس کردن: صفحه بندی/جریان، فشار پشتی.
Fuzz: زمینه ها/هدر ها/مرزهای زمانی.
Compat - SDK های قدیمی ↔ API های جدید و بالعکس.
دود بسته: 5 دقیقه برای گرفتن رگرسیون در CI.

17) تله متری و سیاست های حفظ حریم خصوصی

اختیاری انتخاب کردن در: مجموعه ای از معیارهای SDK جمع (نسخه، زبان، وضعیت) بدون PII.
پیکربندی: «تله متری: خاموش» ناشناس «کامل» (به طور پیش فرض خاموش/ناشناس است).
شفافیت: مستند سازی آنچه اتفاق می افتد و چرا ؛ بیایید جعبه قطع ارتباط را بررسی کنیم.

18) عملکرد و FinOps

دسته بندی: ترکیب پرس و جوهای کوچک ؛ محدود کردن RPS ؛ gzip/br.
ذخیره سازی ETag/If-None-Match، GET مشروط.
مدل های اقتصادی: iterators تنبل به جای بارگذاری همه چیز را به حافظه.
همزمانی با حد: '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}`); }
}

صفحه ساز (پایتون)

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

• خطای مدل واحد («وضعیت»، «خطا _ کد»، «ردیابی _ id»، «قابل بازیابی»).
• Timeouts/retreats/jitter، احترام به 'Retry-After'.
• نوشتن Idempotency، خودکار 'Idempotency-کلید'.
• صفحه بندی مکان نما، iterators تنبل/جریان.
• WebhookVerifier با HMAC/mTLS و deduplication.
• پیکربندی از طریق ENV/سازنده/پارامترها.
• ورود به سیستم/متریک/قلاب OTel، حالت اشکال زدایی بدون اسرار.
• SemVer، احکام ≥90 روز، شاخه های LTS.
• نمونه کامل و کتاب آشپزی در وظایف محبوب.
• ماتریس برابری ویژگی بین زبانها در CI.

22) برنامه پیاده سازی (3 تکرار)

1. MVP (2-3 هفته): مشتری اصلی، auth، 3-5 نقطه پایانی کلیدی، صفحه بندی، مدل خطای تک، retrai/timeouts ؛ TS + پایتون

2. مقیاس (3-5 هفته): جاوا/Go/.NET، WebhookVerifier، نوشتن idempotency، قلاب تله متری، تولید مدل از OpenAPI.
3. طرفدار (مداوم): جریان/SSE/gRPC، بهینه سازی perf، شاخه های LTS، Cookbook گسترده، ابزارهای مهاجرت/کاهش.

23) مینی سوالات متداول

تولید همه چیز و یا نوشتن با دست خود را?
تولید مدل/مشتریان، و ارگونومی (paginators، retrays، idempotency، امضا راحت) - دستی.

آیا من نیاز به یک async-SDK جداگانه دارم ؟

В پایتون - да ('AsyncClient'); در JS - به طور پیش فرض ؛ v.NET/Java - تماس های ناهمزمان در صورت امکان.

چگونه برابری زبان ها را حفظ کنیم ؟

ویژگی ماتریس در CI، انتشار «توسط کمربندها» (TS → Py → Java → Go → .NET) با گزارش خودکار «که عقب مانده است».

مجموع

یک SDK قوی یک سطح واحد، پیش فرض های قابل اعتماد و قراردادهای قابل پیش بینی است که در همه زبان ها یکسان هستند. به توسعه دهندگان تنظیمات امن در خارج از جعبه، یک مدل خطا قابل درک، صفحه بندی مناسب و تایید webhooks، این را با مستندات با کیفیت بالا و semver دقیق تکمیل کنید. سپس یکپارچگی سریع، پشتیبانی ارزان و اکوسیستم پایدار و مقیاس پذیر خواهد بود.