एसडीके डिजाइन और भाषा समर्थन

1) एसडीके लक्ष्य और सफलता मानदंड

डेवलपर अनुभव (DX): सहज ज्ञान युक्त एपीआई, भाषाओं के बीच समान शब्दार्थ।

विश्वसनीयता: बॉक्स से बाहर टाइमआउट/रिट्रीट/आइडेम्पोटेंसी।

सुरक्षा: रहस्य, हस्ताक्षर, टीएलएस, proksi/企业 वातावरण के साथ संगतता।

अवलोकन: भाषा के लिए मानक उपकरणों में लॉग, मैट्रिक्स, निशान।

अर्थव्यवस्था: न्यूनतम अनुगामी/सीपीयू, प्रभावी तमाशा, बैच।

स्थिरता: सख्त सेवर, पिछड़ी संगतता, एलटीएस शाखाएं।

2) वास्तुशिल्प सिद्धांत

1. पतले क्लाइंट, मजबूत अनुबंध: प्रोटोकॉल (REST/gRPC) पर SDK रैपर, बिना छिपे व्यावसायिक तर्क के।

2. एकीकृत सतह: समान अवधारणाएँ (क्लाइंट, अनुरोध, प्रतिक्रिया, त्रुटि, पगिनेटर, वेबहूकवेरिफायर)।

3. डिफ़ॉल्ट रूप से सुरक्षित: उचित टाइमआउट, घातीय बैकऑफ + जिटर, पुनरावृत्ति सुरक्षा।

4. कॉन्फिग लेयरिंग: ENV → कॉन्फिग फ़ाइल → कंस्ट्रक्टर → विधि पैरामीटर।

5. प्लगेबल ट्रांसपोर्ट: HTTP/gRPC हटाने योग्य है, कनेक्शन के साथ संगत है।

6. परीक्षण: इंटरफेस/फेक, निर्भरता इंजेक्शन, रिकॉर्ड-रीप्ले।

7. त्रुटि I18n: मशीन 'error _ codeis स्थिर; संदेश स्थानीय हैं।

8. पहुंच: अतुल्यकालिक वेरिएंट (आमतौर पर 'अतुल्यकालिक क्लाइंट') जहां उपयुक्त हो।

9. सुरक्षा-पहला: यदि आवश्यक हो तो रहस्य लॉग, पीआईआई संस्करण, एफआईपीएस-संगत क्रिप्टो पुस्तकालयों में नहीं आते हैं।

3) तालिका और अवसर समता का समर्थन करें

4) एपीआई बेस सतह (विहित मॉडल)

सामान्य संस्थाएँ

क्लाइंट: परिवहन, कुंजी, रिट्रे, टेलीमेट्री हुक कॉन्फ़िगर करना।

अनुरोध/प्रतिक्रिया: टाइप-सुरक्षित मॉडल/डीटीओ, पैगिनेशन/कर्सर।

त्रुटि: 'status', 'त्रुटि _ 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/',' GH _ RE'।

कंस्ट्रक्टर-ओवरराइड्स ENV।

प्रति-कॉल ओवरराइड: विधि-स्तरीय टाइमआउट/रिट्रे।

TLS/mTLS: प्रमाणपत्र/कुंजी के लिए पथ, यदि आवश्यक हो तो CA पिनिंग.

कनेक्शन पूल: जीवित रखें, HTTP/2, संगामिति बाधा।

6) बॉक्स से बाहर सुरक्षा

राज: लॉग न करें, स्टैक ट्रेस में छुपाएँ; redaction "।

हस्ताक्षर: वेबहुक के लिए HMAC, 'X-Key-Id '/कुंजी रोटेशन, "दो कुंजी" सक्रिय/अगले के लिए समर्थन।

पहचान: 'Idempotency-Key' for लेखन संचालन की पारदर्शी सेटिंग (पुनरारंभ सुरक्षित है)।

RBAC/Scopes: स्कोप के लिए सुविधाजनक गणना/स्थिरांक।

PII नीति: लॉगिंग के लिए मानक संपादन इंटरफेस।

7) विश्वसनीयता: टाइमआउट, रिट्रीट, बैक

डिफ़ॉल्ट टाइमआउट: 10-15s; कनेक्शन 3-5 एस।

रेट्राई: 5xx/408/429 के लिए ('रेट्री-आफ्टर' का सम्मान करें), घातीय बैकऑफ + जिटर, रीट्री/टाइम लिमिट।

सर्किट-ब्रेकर: एसडीके (या तृतीय-पक्ष लिब सिफारिशों) में वैकल्पिक।

पहचान लेखन: कुंजी द्वारा स्वचालित दोहराएँ; टकराव → '409 बढ़ाते हैं। IDEMP_REPLAY'

8) पैगिनेशन, कर्सर और स्ट्रीमिंग

कर्सर/पुनरावृत्ति: आलसी क्रूर बल, क्षणिक त्रुटियों के लिए ऑटो-दोहराता है।

कीसेट पगिनेशन: स्थिर ऑर्डरिंग '(updated_at,id)'।

Backpressure: एक साथ अनुरोध की सीमा; в async-SDK - 'async फॉर '/' चैनल'।

स्ट्रीमिंग (जहां उपलब्ध है): SSE/WebSocket/gRPC-streem के साथ ऑटो-रिकनेक्ट और deduplication 'द्वारा।

9) गलतियाँ और अनुबंध

• 'ApierTerry' (базовый) → подтипы: 'Authere (401)', 'MermentErity (403)', 'NotFound (409)', 'Conflite (429)', 'Validationation Trerry (5xx)'।
• Свойства: 'स्थिति', 'त्रुटि _ कोड', 'संदेश', 'ट्रेस _ आईडी', 'पुनर्प्राप्य', 'विवरण'।
• सर्वश्रेष्ठ अभ्यास: संदेश मानव-पढ़ने योग्य हैं, 'त्रुटि _ कोड' स्थि

10) भाषा मुहावरे

टाइपस्क्रिप्ट/जेएस

पगिनेशन के लिए वादा-आधारित + जनरेटर; ईएसएम + सीजेएस पैकेट।

ट्री-शेकिंग, न्यूनतम पॉलीफाइल, गर्भपात संकेत ('एबॉर्टकंट्रोलर')।

पायथन

सिंक + Async (aiohttp/httpx), संदर्भ प्रबंधक, 'pydantic' मॉडल (या dataclass)।

पहियों для लिनक्स/मैकोस/विंडो; proxies/NO_PROXY समर्थन।

जावा

' Future' (यदि आवश्यक हो), 'ऑटोक्लोसेबल', 'अवधि', 'निष्पादक'।

HTTP क्लाइंट: 'जावा। नेट। http 'या OkHtp; SLF4J लॉग के लिए।

जाओ

संदर्भ का संदर्भ। संदर्भ ',' http। क्लाइंट 'विथ ट्रांसपोर्ट, परीक्षणों के लिए इंटरफेस।

रैपिंग में त्रुटि ('fmt. Errorf ("% w," err) '), त्रुटियों के प्रहरी शब्दार्थ।

.NET

'HttpClientFactory', 'कैंसिलेशनटोकन', 'IAyncEnummable '।

पोली पॉलिसियां (रीट्री/सर्किट-ब्रेकर)।

... PHP/रूबी (PSR-18, फैराडे/नेट: : HTTP) के लिए आदि।

11) लॉगिंग, मैट्रिक्स, ट्रेसिंग

लॉग: स्तर (ERROR/WARN/INFO/DEBUG), सहसंबंध 'trace _ id', संवेदनशील डेटा अक्षम.

Метрики: 'अनुरोध _ कुल', 'त्रुटियाँ _ कुल {स्थिति}', 'retry _ count', 'latency _ ms', 'थ्रोटेल्ड _ टोटल'।

निशान: OpenTelemetry हुक (API कॉल, एंडपॉइंट, स्थिति, रीट्री विशेषताओं के लिए स्पैन)।

डिबग मोड: एनवायरनमेंट वेरिएबल 'GH _ SDK _ DEBUG = 1' - HTTP हेडर (बिना रहस्य के) और समय छाप रहा है.

12) प्रलेखन और उदाहरण

क्विकस्टार्ट 5 मिनट: औथ, पहला अनुरोध, पृष्ठभूमि, 429 प्रसंस्करण।

कुकबुक: वेबहुक (हस्ताक्षर सत्यापन), अज्ञात लेखन, पुनरावृत्ति।

API संदर्भ: OpenAPI/Protobuf से ऑटोजेन, लेकिन "मैनुअल" उदाहरणों के साथ।

स्निपेट्स: लोकप्रिय कार्यों के लिए कोड के तैयार टुकड़े (पायथन/टीएस/जावा/गो/.NET)।

13) जनरेशन बनाम मैनुअल कोडिंग

संयुक्त दृष्टिकोण: कोडेजेन (मॉडल/क्लाइंट) + एर्गोनोमिक्स/आइडेम्पोटेंसी/पेजिनेटर के लिए मैनुअल "पेन"।

टेम्पलेट्स: एक समान विधि नाम ('बनाएँ/get/list/अद्यतन/delete'), छुरा. हस्ताक्षर।

रीजन (सीआई-गेट) के बाद "डिफ-कम्पैटिबिलिटी" की जाँच कर रहा है।

14) वर्शनिंग, संगतता और मूल्यह्रास

SemVer: X.Y.Z. ब्रेकिंग - केवल प्रमुख।

स्थिरता नीति: मामूली रिलीज - क्षेत्र/तरीके जोड़ें, अनुबंध न बदलें।

मूल्यह्रास: एनोटेशन/गुण @ पदावनत/अप्रचलित, प्रति प्रक्रिया एक बार रनटाइम चेतावनी, विंडो ≥ 90 दिन।

LTS शाखाएँ: critfixes का बैकपोर्ट (कोई नई सुविधाएँ नहीं)।

15) रिलीज़ और आपूर्ति श्रृंखला

CI/CD: लिंटर/फॉर्मेटर, यूनिट + एकीकरण, अनुबंध परीक्षण, e2e बनाम सैंडबॉक्स।

आर्टिफ़ैक्ट हस्ताक्षर: सिगस्टोर/जीपीजी, रिलीज़ पर चेकसम।

प्रकाशन: npm/PyPI/Maven/NuGet/Go/Compuser/RubyGems चेंजलॉग और रिलीज नोट्स के साथ।

SemVer गेट: सार्वजनिक API की संगतता की स्वचालित जाँच (उदाहरण के लिए, 'एपिरजिस्ट्री डिफ़')।

16) परीक्षण (गुणवत्ता मैट्रिक्स)

इकाई: मॉडल, क्रमबद्धता, सत्यापन, रिट्रेज ़/टाइमआउट।

संविदा: OpenAPI/Protobuf योजनाओं (नकारात्मक/धार मामले) के खिलाफ।

एकीकरण: बनाम सैंडबॉक्स (पहचान, 429/5xx, वेबहूक)।

लोड/सोक: pagination/stream, backpressure।

फ़ज़: फ़ील्ड/हेडर/समय सीमाएँ।

कॉम्पैट - पुराने एसडीके ↔ नए एपीआई और इसके विपरीत।

स्मोक-पैक: सीआई में एक प्रतिगमन को पकड़ ने के लिए 5 मिनट।

17) टेलीमेट्री और गोपनीयता नीतियां

वैकल्पिक-ऑप्ट-इन: पीआईआई के बिना एकत्र एसडीके मैट्रिक्स (संस्करण, भाषा, स्टेटस) का संग्रह।

कॉन्फ़िग: 'टेलीमेट्री: ऑफ़' अनाम 'फुल' (डिफ़ॉल्ट ऑफ/अनाम है).

पारदर्शिता: दस्तावेज़ क्या होने वाला है और क्यों; चलो डिस्कनेक्ट बॉक्स की जाँच करें।

18) प्रदर्शन और फिनोप्स

बैचिंग: छोटे प्रश्नों को जोड़ें; आरपीएस को सीमित करें; gzip/br।

ETag/इफ-नो-मैच कैशिंग, सशर्त GET।

किफायती मॉडल: स्मृति में सब कुछ लोड करने के बजाय आलसी पुनरावृत्ति।

सीमा के साथ संगोष्ठी: 'max _ concurrency' ताकि "DDOS" API न हो।

19) विशिष्ट एसडीके घटक (कंकाल)

त्रुटि (टाइपस्क्रिप्ट)

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) समर्थन, एसएलए और समुदाय

एसडीके द्वारा एसएलए: महत्वपूर्ण कीड़े - ईटीए, संचार चैनल, संगतता मैट्रिक्स (SDK↔API) को ठीक करें।

टेम्पलेट जारी करें: बग/फीचर/प्रश्न, भाषा/संस्करण द्वारा स्वतः ट्राइएज।

रोडमैप/लेबल: "अच्छा पहला मुद्दा", "मदद चाहता था।"

सुरक्षा नीति: 'सुरक्षा। md ', कमजोरियों की रिपोर्टिंग के लिए चैनल, यदि आवश्यक हो तो CVE।

21) एसडीके क्वालिटी चेकलिस्ट

• एकल मॉडल त्रुटि ('स्थिति', 'त्रुटि _ कोड', 'ट्रेस _ आईडी', 'पुनर्प्राप्य')।
• टाइमआउट/रिट्रीट/जिटर, 'रेट्री-आफ्टर' के लिए सम्मान।
• आइडेम्पोटेंसी राइट, स्वचालित 'आइडेम्पोटेंसी-की'।
• कर्सर पगिनेशन, आलसी पुनरावृत्तियाँ/धाराएँ।
• HMAC/mTLS और deduplication के साथ WebhookVerifier।
• ईएनवी/कंस्ट्रक्टर/पैरामीटर के माध्यम से कॉन्फ़िगरेशन।
• लॉगिंग/मेट्रिक्स/ओटेल हुक, बिना रहस्य के डिबग मोड।
• SemVer, ≥90 दिनों की कमी, LTS शाखाएँ।
• लोकप्रिय कार्यों पर उदाहरण और कुकबुक पूरा करें।
• सीआई में भाषाओं के बीच फ़ीचर समता मैट्रिक्स।

22) कार्यान्वयन योजना (3 पुनरावृत्ति)

1. एमवीपी (2-3 सप्ताह): बुनियादी क्लाइंट, ऑथ, 3-5 प्रमुख एंडपॉइंट, पैगिनेशन, सिंगल एरर-मॉडल, रेट्राई/टाइमआउट; टीएस + पायथन।

2. स्केल (3-5 सप्ताह): जावा/गो/.NET, वेबहूकवेरिफायर, आइडेम्पोटेंसी राइट, टेलीमेट्री हुक, ओपनएपीआई से मॉडल बनाना।

3. प्रो (निरंतर): स्ट्रीमिंग/एसएसई/जीआरपीसी, पर्फ ऑप्टिमाइजेशन, एलटीएस शाखाएं, विस्तारित कुकबुक, माइग्रेशन/डिक्रेशन टूल।

23) मिनी-एफएक्यू

सब कुछ उत्पन्न करें या अपने हाथों से लिखें?

मॉडल/क्लाइंट, और एर्गोनोमिक्स (पेजिनेटर, रिट्रे, आइडेम्पोटेंसी, सुविधाजनक हस्ताक्षर) उत्पन्न करें - मैन्युअल रूप से।

क्या मुझे एक अलग Async-SDK की आवश्यकता है?

В पायथन - да ('AsyncClient'); जेएस में - डिफ़ॉल्ट रूप से; v.NET/जावा - अतुल्यकालिक कॉल यदि संभव हो।

भाषाओं की समानता कैसे रखें?

CI में मैट्रिक्स फीचर, ऑटो-रिपोर्ट के साथ "बेल्ट द्वारा" (TS→Py→Java→Go→.NET) जारी करता है "जो पिछड़ जाता है।"

कुल

एक मजबूत एसडीके एक एकल सतह, विश्वसनीय चूक और अनुमानित अनुबंध है जो सभी भाषाओं में समान हैं। डेवलपर्स को बॉक्स से बाहर सुरक्षित सेटिंग्स, एक समझने योग्य त्रुटि-मॉडल, वेबहुक के सुविधाजनक तमाशा और सत्यापन दें, इसे उच्च गुणवत्ता वाले प्रलेखन और सख्त सेवर के साथ पूरा करें। फिर एकीकरण तेज होगा, समर्थन सस्ता होगा, और पारिस्थितिकी तंत्र टिकाऊ और स्केलेबल होगा।