SDK დიზაინი და ენების მხარდაჭერა

1) SDK მიზნები და წარმატების კრიტერიუმები

დეველოპერის გამოცდილება (DX): ინტუიციური API, ენებს შორის ერთიანი სემანტიკა.
საიმედოობა: taimauts/retrais/idempotence „ყუთიდან“.
უსაფრთხოება: საიდუმლოებები, ხელმოწერები, TLS, თავსებადობა მარიონეტულ/მედიასთან.
დაკვირვება: ლოგოები, მეტრიკები, სტანდარტული ინსტრუმენტები ენისთვის.
ეკონომიკა: მინიმალური egress/CPU, ეფექტური პაგინაცია, ბრძოლები.
სტაბილურობა: მკაცრი სემვერი, საპირისპირო თავსებადობა, LTS ფილიალები.

2) არქიტექტურული პრინციპები

1. Thin client, strong contracts: SDK შეფუთვა პროტოკოლზე (REST/gRPC), ფარული ბიზნეს ლოგიკის გარეშე.
2. Unified surface: იგივე ცნებები (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Safe by default: გონივრული ტაიმაუტები, ექსპონენციალური backoff + jitter, გამეორებისგან დაცვა.
4. Config layering: ENV - კონფიგურაციის ფაილი, დიზაინერი - მეთოდის პარამეტრები.
5. Pluggable ტრანსპორტი: HTTP/gRPC შეცვლილია, შეესაბამება მარიონეტულ/მარიონეტულ ნაერთებს.
6. Testability: ინტერფეისები/ყალბი, დეპენდენტაცია, ჩანაწერები.
7. I18n შეცდომები: ძრავა 'error _ code' სტაბილურია; შეტყობინებები ლოკალიზებულია.
8. Accessibility: ასინქრონული ვარიანტები (ჩვეულებრივ 'AsyncClient') იქ, სადაც მიზანშეწონილია.
9. უსაფრთხოების პირველი: საიდუმლოებები არ შედის ლოგოებში, PII რედაქტორებში, საჭიროების შემთხვევაში FIPS თავსებადი კრიპტობიოტეკებში.

3) დამხმარე ცხრილი და შესაძლებლობების პარიტეტი

4) API- ს ძირითადი ზედაპირი (კანონიკური მოდელი)

ზოგადი არსებები

კლიენტი: ტრანსპორტის, გასაღებების, რეაგირების, ტელემეტრიული ჰოკსის კონფიგურაცია.
Request/Response: ტიპის უსაფრთხოების მოდელები/DTO, პაგინაცია/კურსორები.
Error: ერთი კლასი 'status', 'error _ code', 'trace _ id', 'retriable'.
Paginator/Iterator: გვერდების/კურსორების ზარმაცი ძებნა.
WebhookVerifier: HMAC/mTLS შემოწმება, 'ღონისძიების _ 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_PROXY`, `GH_REGION`.
დიზაინერი: განსაზღვრავს ENV- ს.
Per-call overrides: taymaut/retrai მეთოდის დონეზე.
TLS/mTLS: სერთიფიკატის/გასაღების გზა, საჭიროების შემთხვევაში pinning CA.
ნაერთების აუზები: keep-alive, HTTP/2, პარალელიზმის შეზღუდვა.

6) უსაფრთხოება ყუთიდან

საიდუმლოებები: არ მოაწყოთ, დამალოთ თავდასხმა; redaction ``.
ხელმოწერები: HMAC ვებჰუკებისთვის, 'X-Key-Id '/გასაღებების როტაცია, აქტიური/შემდეგი „ორი გასაღების“ მხარდაჭერა.
Idempotence: გამჭვირვალე ინსტალაცია 'Idempotency-Key' თავისუფალი ოპერაციებისთვის (გადატვირთვა უსაფრთხოა).
RBAC/Scopes: მოსახერხებელი ჩამოთვლა/მუდმივი ნაგავსაყრელი.
PII პოლიტიკა: სტანდარტული რედაქტირების ინტერფეისები.

7) საიმედოობა: Taimauts, retrai, უკანა ოფები

ნაგულისხმევი ტაიმუთი: 10-15s; კონექტორი 3-5 ს.
Retrai: 5xx/408/429 (პატივისცემა 'Retry-After'), ექსპონენციალური backoff + jitter, მცდელობების/დროის ზღვარი.
Circuit-breaker: სურვილისამებრ SDK (ან რეკომენდაციები მესამე მხარის ლიბამის შესახებ).
Idempotent write: ავტომატური გამეორება; კონფლიქტები შეიძლება გაიზარდოს '409 IDEMP _ REPLAY'.

8) პაგინაცია, კურსორები და ნაკადი

კურსორი/გამეორება: ზარმაცი ძებნა, მანქანების გამეორება ტრანზიენტული შეცდომებით.
Keyset pagination: სტაბილური მოწესრიგება '(განახლება _ at, id)'.
Backpressure: ერთდროული მოთხოვნის ლიმიტი; в async-SDK — `async for`/`channels`.
სტრიმინგი (სადაც ხელმისაწვდომია): SSE/WebSocket/grRPC-stream მანქანით-ჩანაწერებით და 'sequence' ბაბუა.

9) შეცდომები და კონტრაქტი

• `ApiError` (базовый) → подтипы: `AuthError(401)`, `PermissionError(403)`, `NotFound(404)`, `Conflict(409)`, `RateLimit(429)`, `ValidationError(422)`, `ServerError(5xx)`.
• Свойства: `status`, `error_code`, `message`, `trace_id`, `retriable`, `details`.
• საუკეთესო პრაქტიკა: შეტყობინებები - ადამიანური, 'error _ code' - სტაბილური.

10) ენის იდიომები

TypeScript/JS

Promise-based + გენერატორები პაგინაციისთვის; ESM + CJS პაკეტები.
Ree shaking, მინიმალური პოლიფილები, abort სიგნალები ('Abort Controller').

Python

Sync + Async (aiohttp/httpx), კონტექსტის მენეჯერები, „pydantic“ მოდელები (ან მონაცემთა ბაზები).
Wheels для linux/macos/windows; Proxies/NO _ PROXY მხარდაჭერა.

Java

'CompletableFuture' (საჭიროების შემთხვევაში), 'AutoCloseable', 'Duration', 'Executor'.
HTTP client: `java. net. http 'ან Okhtt; SLF4J ლოგებისთვის.

Go

კონტექსტები 'context. Context`, `http. Client's tuned Transport, ტესტის ინტერფეისები.
Error wrapping (`fmt. ერორფი („% w“, err) '), sentinel შეცდომების სემანტიკა.

.NET

`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.
პოლიტიკოსები (retry/circuit-breaker).

... და ა.შ. PHP/Ruby (PSR-18, Faraday/Net:: HTTP).

11) ლოგიკა, მეტრიკა, ტრეკერი

Logs: დონე (ERROR/WARN/INFO/DEBUG), კორელაცია 'trace _ id', მგრძნობიარე მონაცემების გათიშვა.
Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.
მარშრუტები: OpenTelemetry hooks (spen ზარის API, ატრიბუტები endpoint, status, retry).
Debug-mode: ცვლადი გარემო 'GH _ SDK _ DEBUG = 1' - HTTP სათაურების ბეჭედი (საიდუმლოებების გარეშე) და დრო.

12) დოკუმენტაცია და მაგალითები

Quickstart 5 წუთი: auth, პირველი მოთხოვნა, პაგინაცია, დამუშავება 429.
Cookbook: webhooks (ხელმოწერის შემოწმება), idempotent write, raples.
API ცნობარი: ავტოგენი OpenAPI/Protobuf- დან, მაგრამ „სახელმძღვანელო“ მაგალითებით.
Snippets: მზა კოდების ნაწილები პოპულარული დავალებებისთვის (Python/TS/Java/Go/.NET).

13) სახელმძღვანელო კოდირების წარმოება

კომბინირებული მიდგომა: codegen (მოდელები/მომხმარებლები) + სახელმძღვანელო „სახელურები“ ergonomics/idempotenty/paginators.
შაბლონები: მეთოდების ერთიანი სახელები ('create/get/list/განახლება/delete'), create. ხელმოწერები.
„diff თავსებადობის“ შემოწმება რეგენის შემდეგ (CI კარიბჭე).

14) ვერსია, თავსებადობა და დეპრესია

SemVer: X.Y.Z. გატეხილი - მხოლოდ მაიორი.
სტაბილურობის პოლიტიკა: უმცირესობის გამოშვებები - დაამატეთ ველები/მეთოდები, არ შეცვლიან კონტრაქტებს.
Deprecation: ვიდეოები/ატრიბუტები @ Deprecated/Obsolete, rantime გაფრთხილებები პროცესზე ერთხელ, ფანჯარა 90 დღე.
LTS ფილიალები: კრიტიკის პაკეტი (ახალი შეცდომების გარეშე).

15) გამოშვებები და მიწოდების ჯაჭვი

CI/CD: linters/formula, unit + integration, კონტრაქტის ტესტები, e2e ქვიშის ყუთის წინააღმდეგ.
არტეფაქტების ხელმოწერა: Sigstore/GPG, checksums გამოშვებებზე.
პუბლიკაცია: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems ერთად changelog და release notes.
SemVer gate: საზოგადოებრივი API- ის თავსებადობის მანქანა (მაგალითად, 'apiregistry diff').

16) ტესტირება (ხარისხის მატრიცა)

Unit: მოდელები, სერიალიზაცია, შესაბამისობა, retrai/Taimauts.
Contract: OpenAPI/Protobuf- ის წინააღმდეგ (negative/edge cases).
Integration: sandbox- ის წინააღმდეგ (იდემპოტენტობა, 429/5xx, webhooks).
Load/soak: pagination/strim, backpressure.
Fuzz: ველები/სათაურები/დროის საზღვრები.
კომპატი: ძველი SDK არის ახალი API და პირიქით.
Smoke-pack: 5 წუთი CI- ში რეგრესიის მოსაპოვებლად.

17) ტელემეტრიისა და კონფიდენციალურობის პოლიტიკა

სურვილისამებრ-opt-in: საერთო მეტრიკის SDK შეგროვება (ვერსია, ენა, სტატუსი) PII- ის გარეშე.
კონფიგურაცია: 'telemetry: off' anonymized 'full' (ნაგულისხმევი off/anonymized).
გამჭვირვალობა: დოკუმენტაცია, რა და რატომ აპირებს; მოდით, დროშა გამორთოთ.

18) პროდუქტიულობა და FinOps

Batching: მცირე მოთხოვნების გაერთიანება; შეზღუდული RPS; gzip/br.
ETag/If-None-Match ქეშირება, პირობითი GET.
ეკონომიკური მოდელები: ზარმაცი გამეორებები, იმის ნაცვლად, რომ დატვირთვას ყველაფერი მეხსიერებაში.
პარალელიზმი ლიმიტით: 'max _ concurrency' ისე, რომ არ „DDOSite“ API.

19) SDK ტიპის კომპონენტები (ჩონჩხი)

Error (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}`); }
}

პითონი

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 და საზოგადოება

SLA SDK: კრიტიკული შეცდომები - fix ETA, საკომუნიკაციო არხები, თავსებადობის მატრიცა (SDK-API).
Issue templates: bug/feature/question, auto-triage ენაზე/ვერსიაში.
Roadmap/labels: «good first issue», «help wanted».
Security policy: `SECURITY. md ', დაუცველობის ანგარიშების არხი, საჭიროების შემთხვევაში CVE.

21) SDK ხარისხის ჩეკის სია

• ერთი შეცდომა მოდელი ('status', 'error _ code', 'trace _ id', 'retrable').
• Taimauty/retrai/jitter, პატივისცემა 'Retry-After'.
• write idempotence, ავტომატური 'Idempotency-Key'.
• კურსორის პაგინაცია, ზარმაცი გამეორება/ნაკადები.
• Webhook Verifier ერთად HMAC/mTLS და ბაბუა.
• კონფიგურაცია ENV/დიზაინერის/პარამეტრების საშუალებით.
• ლოგიკა/მეტრიკა/OTel-huks, debug რეჟიმი საიდუმლოების გარეშე.
• SemVer, დეპრესიები 90 დღე, LTS ფილიალები.
• სრული მაგალითები და Cookbook პოპულარულ დავალებებში.
• პარიტეტული პარიტეტის მატრიცა CI- ს ენებს შორის.

22) განხორციელების გეგმა (3 გამეორება)

1. MVP (2-3 კვირა): ძირითადი კლიენტი, aut, 3-5 ძირითადი ენდოინტი, პაგინაცია, ერთი შეცდომა მოდელი, retrai/Taimauts; TS+Python.
2. Scale (3-5 კვირა): Java/Go/.NET, Webhock Verifier, idempotence write, hooks ტელემეტრია, მოდელების გამომუშავება OpenAPI- დან.
3. Pro (მუდმივად): ნაკადი/SSE/gRPC, perf ოპტიმიზაცია, LTS ფილიალები, გაფართოებული Cookbook, მიგრაციის/დეპრესიის ინსტრუმენტები.

23) მინი-FAQ

ჩამოაყალიბეთ ყველაფერი ან დაწერეთ ხელები?
წარმოქმნის მოდელებს/მომხმარებლებს, ხოლო ergonomics (პაგინატორები, რეტრატორები, იდემპოტენტობა, მოსახერხებელი ხელმოწერები) ხელით.

საჭიროა ცალკე async-SDK?
В Python — да (`AsyncClient`); JS- ში - ნაგულისხმევი; NET/Java - ასინქრონული გამოწვევები, თუ ეს შესაძლებელია.

როგორ შევინარჩუნოთ ენების პარიტეტი?
Fich მატრიცა CI- ში, გამოშვებები „ქამრებზე“ (TS-Py-Java-Go-.NET) მანქანების ანგარიშით „რაც ჩამორჩება“.

შედეგი

ძლიერი SDK არის ერთიანი ზედაპირი, საიმედო ნაგულისხმევი და პროგნოზირებადი კონტრაქტები, რომლებიც იგივეა ყველა ენაზე. მიეცით დეველოპერებს უსაფრთხო პარამეტრები „ყუთიდან“, გასაგები შეცდომის მოდელი, მოსახერხებელი პაგინაცია და ვებჰუკების გადამოწმება, დაასრულეთ ეს მაღალი ხარისხის დოკუმენტაციით და მკაცრი სიმვერით. შემდეგ ინტეგრაცია სწრაფი იქნება, მხარდაჭერა - იაფი, ხოლო ეკოსისტემა - სტაბილური და მასშტაბური.