تصميم SDK والدعم اللغوي

1) أهداف SDK ومعايير النجاح

تجربة المطور (DX): واجهات برمجة تطبيقات بديهية، دلالات موحدة بين اللغات.
الموثوقية: المهلات/التراجعات/الخصوصية خارج الصندوق.
الأمن: الأسرار، التوقيعات، TLS، التوافق مع البيئات proksi/企业.
إمكانية الملاحظة: السجلات والمقاييس والآثار في الأدوات القياسية للغة.
الاقتصاد: الحد الأدنى للخروج/وحدة المعالجة المركزية، الاستعداد الفعال، الدفعات.
الاستقرار: نصف النهائي الصارم، التوافق الخلفي، فروع LTS.

2) المبادئ المعمارية

1. عميل رقيق، عقود قوية: غلاف SDK فوق البروتوكول (REST/gRPC)، دون منطق عمل خفي.
2. السطح الموحد: نفس المفاهيم (العميل، الطلب، الرد، الخطأ، Paginator، WebhookVerifier).
3. آمن افتراضيًا: مهلة معقولة، تراجع أسي + نفث، حماية التكرار.
4. تكوين الطبقات: ENV → تكوين ملف → بناء → طريقة المعلمات.
5. النقل القابل للسد: HTTP/gRPC قابل للإزالة ومتوافق مع proksi/池 الاتصال.
6. قابلية الاختبار: واجهات/مزيفة، حقن التبعية، إعادة تشغيل السجلات.
7. الخطأ I18n: «خطأ» الآلة مستقر ؛ الرسائل قابلة للتوزيع.
8. إمكانية الوصول: المتغيرات غير المتزامنة (عادة «AsyncClient») عند الاقتضاء.
9. الأمان أولاً: لا تقع الأسرار في جذوع الأشجار، إصدار PII، مكتبات التشفير المتوافقة مع FIPS إذا لزم الأمر.

3) دعم الطاولة وتكافؤ الفرص

4) سطح قاعدة واجهة برمجة التطبيقات (نموذج قانوني)

الكيانات المشتركة

العميل: تهيئة النقل، المفاتيح، إعادة التصوير، خطافات القياس عن بعد.
الطلب/الاستجابة: النماذج المأمونة من النوع/إدارة التجارة، التثبيت/المؤشرات.
خطأ: فئة واحدة مع "status'،" خطأ _ رمز "،" تتبع _ معرف "،" قابل للاسترجاع ".
Paginator/Iterator: بحث كسول عن الصفحات/المؤشرات.
WebhookVerifier: HMAC/mTLS check، dedup بواسطة "event _ id'.

مثال صغير (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 })) { /... / }

مثال مصغر (بايثون، أسينك)

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 _ PRO"، "GH H _ RE".
المبني فوق ENV.
تجاوزات لكل مكالمة: مهلة/إعادة تشغيل على مستوى الطريقة.
TLS/mTLS: المسار إلى الشهادة/المفتاح، تثبيت CA إذا لزم الأمر.
مجمعات الاتصال: البقاء على قيد الحياة، HTTP/2، قيود متزامنة.

6) السلامة خارج الصندوق

الأسرار: لا تسجل، اختبئ في آثار مكدسة ؛ التنقيح ".
التوقيعات: HMAC لخطافات الويب، «X-Key-Id »/دوران المفتاح، دعم« مفتاحين »نشطين/تاليين.
الخصوصية: الإعداد الشفاف لـ «Idempotency-Key» لعمليات الكتابة (إعادة التشغيل آمنة).
RBAC/Scopes: عدد مناسب/ثوابت للنطاقات.
سياسة PII: واجهات التحرير القياسية للتسجيل.

7) الموثوقية: المهلة، التراجعات، الظهور

المهلة الافتراضية: 10-15 ثانية ؛ الاتصال 3-5s.
Retrai: لـ 5xx/408/429 (الاحترام «Retry-After»)، التراجع الأسي + jitter، إعادة المحاولة/الحد الزمني.
قاطع الدائرة: اختياري في SDK (أو توصيات الطرف الثالث).

الكتابة الخفية: التكرار التلقائي بالمفتاح ؛ الاصطدامات → رفع '409. IDEMP_REPLAY'

8) التثبيت والمؤشرات والبث

المؤشر/المكرر: قوة غاشمة كسولة، تكرار تلقائي للأخطاء العابرة.
Keyset pagination: stable ordering '(updated_at,id)'.
الضغط الخلفي: الحد الأقصى للطلبات المتزامنة ؛ в async-SDK - 'async for '/' channels'.
البث (حيثما كان متاحًا): SSE/WebSocket/gRPC-stream مع إعادة الاتصال التلقائي والتفريغ بواسطة «التسلسل».

9) الأخطاء والعقد

• "ApiError" (базовый) → подтипы: "AuthError (401)"، "خطأ الإذن (403)"، "NotFound (404)"، "Conflict (409)"، "RateLimite (429)"، "خطأ التحقق (422)"، "SEre خطأ verError (5xx) '.
• Свойства: «حالة»، «خطأ _ رمز»، «رسالة»، «تتبع _ معرف»، «قابل للاسترجاع»، «تفاصيل».
• أفضل الممارسات: الرسائل قابلة للقراءة من قبل الإنسان، «خطأ _ رمز» مستقر.

10) المصطلحات اللغوية

TypeScript/JS

مولدات كهربائية قائمة على الوعد + للتجميع ؛ حزم ESM + CJS.
اهتزاز الأشجار، الحد الأدنى من البوليفيلات، إجهاض الإشارات («AbortController»).

بايثون

Sync + Async (aiohttp/httpx)، مديري السياق، نماذج «pydantic» (أو dataclasses).
عجلات для لينكس/ماكو/نوافذ ؛ proxies/NO_PROXY الدعم.

جافا

«المستقبل الكامل» (إذا لزم الأمر)، «AutoClosable»، «المدة»، «المنفذ».

عميل HTTP: 'جافا. صافي. http 'أو OkHttp ؛ SLF4J لجذوع الأشجار

اذهب

سياق السياقات. السياق "، http. العميل مع ضبط النقل، واجهات للاختبارات.
تغليف الخطأ ('fmt. Errorf («% w»، «خطأ»)، دلالات الأخطاء الحراسة.

.NET

«HttpClientFactory» و «CancellationToken» و «IAsyncEnumerable <T>».
سياسات بولي (إعادة/قاطع الدائرة).

... إلخ لـ PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) قطع الأشجار والمقاييس والتعقب

Logs: legals (خطأ/WARN/INFO/DEBUG), correction 'trace _ id', disabling sensitive data.
Метрики: "الطلبات _ المجموع"، "الأخطاء _ المجموع {الحالة}"، "إعادة النظر _ العد"، "الكمون _ ms'،" الاختناق _ المجموع ".
الآثار: خطافات OpenTelemetry (تمتد إلى مكالمة API، نقطة النهاية، الحالة، سمات إعادة التجربة).
Debug-mode: environmental variable 'GH _ SDK _ DEBUG = 1' - طباعة رؤوس HTTP (بدون أسرار) والأوقات.

12) الوثائق والأمثلة

Quickstart 5 دقائق: auth، الطلب الأول، pagination، 429 معالجة.
كتاب الطبخ: خطافات الويب (التحقق من التوقيع)، الكتابة الخفية، إعادة التشغيل.
مرجع واجهة برمجة التطبيقات: Autogen من OpenAPI/Protobuf، ولكن مع أمثلة «يدوية».
مقتطفات: قطع كود جاهزة للمهام الشعبية (Python/TS/Java/Go/.NET).

13) الترميز اليدوي من الجيل مقابل

النهج المشترك: codegen (النماذج/العملاء) + «الأقلام» اليدوية لعلم بيئة العمل/الخصوصية/المعالجات.
النماذج: أسماء الأساليب الموحدة ('إنشاء/الحصول على/قائمة/تحديث/حذف')، طعنة. التوقيعات.
التحقق من «توافق diff» بعد regen (بوابة CI).

14) الحرث والتوافق والاستنفاد

SemVer: X.Y.Z. كسر - تخصص فقط.
سياسة الاستقرار: إطلاقات طفيفة - إضافة حقول/أساليب، لا تغير العقود.
الاستنكار: شروح/سمات @ Deprecated/Alcolete، تحذيرات وقت التشغيل مرة واحدة لكل عملية، نافذة ≥ 90 يومًا.
فروع LTS: backport of critfixes (لا توجد ميزات جديدة).

15) الإصدارات وسلسلة التوريد

CI/CD: بطانات/صيغ، وحدة + تكامل، اختبارات العقد، e2e مقابل صندوق الرمل.
توقيع القطع الأثرية: Sigstore/GPG، الشيكات على الإصدارات.
النشر: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems مع ملاحظات التغيير والإصدار.
بوابة SemVer: التحقق التلقائي من توافق واجهة برمجة التطبيقات العامة (على سبيل المثال، «apiregistry diff»).

16) الاختبار (مصفوفة الجودة)

الوحدة: النماذج، التسلسل، المصادقة، إعادة التصوير/المهلات.
العقد: ضد مخططات OpenAPI/Protobuf (قضايا سلبية/حافة).
التكامل: مقابل صندوق الرمل (الخصوصية، 429/5xx، الخطابات الشبكية).
الحمل/النقع: الوثب/التيار، الضغط الخلفي.
الزغب: الحقول/الرؤوس/حدود الوقت.
Compat - SDKs القديمة ↔ واجهات برمجة التطبيقات الجديدة والعكس صحيح.
حزمة الدخان: 5 دقائق لالتقاط تراجع في CI.

17) سياسات القياس عن بعد والخصوصية

اختياري الاختيار: مجموعة مقاييس SDK المجمعة (النسخة واللغة والأوضاع) بدون PII.
التكوين: «القياس عن بعد: إيقاف» مجهول «ممتلئ» (الافتراضي معطل/مجهول).
الشفافية: توثيق ما سيحدث ولماذا ؛ دعونا نتحقق من صندوق قطع الاتصال.

18) الأداء و FinOps

الدفع: جمع الاستفسارات الصغيرة ؛ الحد من RPS ؛ gzip/br.
ETag/If-None-Match Caching، احصل على شرطي.
النماذج الاقتصادية: مكررات كسولة بدلاً من تحميل كل شيء في الذاكرة.
التوافق مع الحد: «max _ concurrency» حتى لا «DDOS» واجهة برمجة التطبيقات.

19) مكونات SDK النموذجية (الهياكل العظمية)

خطأ (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 (بايثون)

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) الدعم وجيش تحرير السودان والمجتمع المحلي

SLA by SDK: الأخطاء الحرجة - إصلاح ETA، قنوات الاتصال، مصفوفة التوافق (SDK↔API).
نماذج الإصدار: خطأ/ميزة/سؤال، فرز تلقائي حسب اللغة/الإصدار.
خارطة الطريق/الملصقات: «العدد الأول الجيد»، «المساعدة المطلوبة».
السياسة الأمنية: 'الأمن. md '، قناة للإبلاغ عن نقاط الضعف، CVE إذا لزم الأمر.

21) قائمة مراجعة جودة SDK

• خطأ نموذج واحد ('حالة'، 'خطأ _ رمز'، 'تتبع _ id'،' استرجاع ').
• Timeouts/retreats/jitter، احترام «Retry-After».
• كتابة الخصوصية، «مفتاح الخصوصية» التلقائي.
• ترقيم المؤشر، مكررات/تيارات كسولة.
• WebhookVerifier مع HMAC/mTLS والتفريغ.
• التشكيل عن طريق ENV/البناء/البارامترات.
• قطع الأشجار/المقاييس/خطافات OTEL، وضع التصحيح بدون أسرار.
• SemVer، تخفيضات ≥90 أيام، فروع LTS.
• أمثلة كاملة وكتاب طبخ عن المهام الشعبية.
• ميزة مصفوفة التكافؤ بين اللغات في CI.

22) خطة التنفيذ (3 تكرارات)

1. MVP (2-3 أسابيع): العميل الأساسي، auth، 3-5 نقاط النهاية الرئيسية، pagination، نموذج خطأ واحد، retrai/timeouts ؛ TS + Python.
2. المقياس (3-5 أسابيع): Java/Go/.NET، WebhookVerifier، كتابة الخصوصية، خطافات القياس عن بعد، توليد النماذج من OpenAPI.
3. Pro (مستمر): البث/SSE/gRPC، تحسينات perf، فروع LTS، كتاب الطبخ الموسع، أدوات الهجرة/التخفيض.

23) الأسئلة الشائعة المصغرة

توليد كل شيء أو الكتابة بيديك ؟

توليد النماذج/العملاء، وعلم بيئة العمل (paginators، retrays، idempotency، التوقيعات المريحة) - يدويًا.

هل أحتاج إلى async-SDK منفصل ؟

В بايثون - да (AsyncClient) ؛ في الورقة المشتركة - افتراضياً ؛ v.NET/Java - مكالمات غير متزامنة إن أمكن.

كيف تحافظ على تكافؤ اللغات ؟

ميزة المصفوفة في CI، تصدر «بالأحزمة» (TS→Py→Java→Go→.NET) مع تقرير تلقائي «يتخلف عن الركب».

المجموع

SDK القوي هو سطح واحد، وتخلف موثوق به وعقود يمكن التنبؤ بها متشابهة في جميع اللغات. امنح المطورين إعدادات آمنة خارج الصندوق، ونموذجًا مفهومًا للأخطاء، واستعدادًا مناسبًا والتحقق من خطوط الويب، وأكمل ذلك بوثائق عالية الجودة ونصف صارم. ثم ستكون عمليات التكامل سريعة، والدعم رخيص، والنظام البيئي مستدام وقابل للتطوير.