MSK դիզայն և աջակցություն լեզուների

1) KPK նպատակները և հաջողության չափանիշները

Developer Experience (DX): ինտուիտիվ API, լեզուների միջև միասնական սեմանտիկ։

Տե՛ ս ՝ թայմաուտներ/ռետտա/idempotenty «տուփից»։

Անվտանգությունը 'գաղտնիքները, ստորագրությունները, TSA-ը, համատեղելիությունը 108/105-ի հետ։

Դիտարկումը 'լոգներ, չափումներ, ուղիներ ստանդարտ գործիքների համար։

Տնտեսությունը 'առնվազն egress/CPU, արդյունավետ պագինացիա, բատչեր։

Մոսկվա 'խիստ semver, հակառակը համատեղելիությունը, LTS-ճյուղերը։

2) Ճարտարապետական սկզբունքները

1. THiN client, strong www.rac.ru: MSK ծածկագիրը (REST/gRPC), առանց թաքնված բիզնես տրամաբանության։

2. Unified surface: Նույն հասկացությունները (Client, Request, Response, Error, Paginae, Webhae Verifier)։

3. Safe by 210: խելացի թայմաուտներ, էքսպոնենցիալ backoff + jitter, պաշտպանություն խոհարարներից։

4. Internewlayering: ENV www.orlg-flame-ը տեխնիկական մեթոդի պարամետրերի դիզայներ է։

5. Pluggable transport: HTTP/gRPC փոխարինում են, համատեղելի են 108/108-ի հետ։

6. Testability: ինտերֆեյսներ/ֆեյքեր, dependency inject, record-replay։

7. I18n սխալներ 'մեքենայական' error _ code 'medillen; հաղորդագրությունները։

8. Accessibility: Ասինխրոն տարբերակները (սովորաբար «AsynccClient») այնտեղ, որտեղ դա տեղին է։

9. System-first: գաղտնիքները չեն ընկնում լոգայի, PII խմբագրության, FIPS-համատեղելի cryptoblioteks անհրաժեշտության դեպքում։

3) Աջակցելու և հավասարեցնելու հնարավորությունները

4) API (կանոնական մոդել)

Ընդհանուր էակներ

Client 'տեղափոխման, երթևեկության, հոսանքի, telemetry hooks։

Request/Response: Տիպային մոդելներ/DTO, պագինացիա/կուրսորներ։

Error 'մեկ դաս' «status», «error _ code», «trace _ id», «retriable»։

Pagin.ru/Iter.ru: Էջերի/կուրսորների ծույլ ընդհատումը։

Webhair Verifier: HMAC/mTSA-ի ստուգումը, «event _ id» դեդուպը։

Մինի օրինակ (Windows Script)

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 })) { /... / }

Մինի օրինակ (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) Կազմաձևման և իրականացման միջավայրը

ENV: `GH_API_KEY`, `GH_ENDPOINT`, `GH_TIMEOUT_MS`, `HTTP_PROXY/HTTPS_PROXY`, `GH_REGION`.

Դիզայներ 'վերարտադրում է ENV-ը։

Per-call overrides: Timaut/retray մեթոդի մակարդակում։

TFC/mTSA 'հավաստագրի/բանալին, pinning CA-ը անհրաժեշտության դեպքում։

Պուլները ՝ keep-alive, HTTP/2, զուգահեռականության սահմանափակումը։

6) Ապահովությունը արկղից

Գաղտնիքները ՝ ոչ տրամաբանել, թաքցնել stack traces; redaction ``.

Ստորագրություններ ՝ HMAC webhuks, «X-Key-Id »/կոդավորման համար,« երկու պարամետրերի »աջակցությունը active/next։

Idempotenty: Թափանցիկ տեղադրում «Idempotency-Key» -ը write վիրահատությունների համար (վերականգնումը անվտանգ է)։

RBAC/Scopes: հարմար թվեր/կայունություններ մոտոցիկլետների համար։

PII քաղաքականությունը 'խմբագրման ինտերֆեյսները լոգարիթմացման ժամանակ։

7) Իսպանիա ՝ թայմաուտներ, ռետրաններ, Back-փլեյ-օֆֆ

Թայմաութը լռելյայն '10-15c; կոննեկտ 3-5c.

Retrai: 5xx/4.9/429 համար (հարգել «Retry-After»), էքսպոնենցիալ backoff + jitter, փորձերի/ժամանակի սահմանը։

Circuit-breaker: Openation CPK-ում (կամ առաջարկությունները երրորդ լիբների համար)։

Idempotent write: Ավտոմատ հաշվիչ բանալին; Կոլիզիան պատրաստվում է բարձրացնել '409 IDEMP _ REPLAY "։

8) Պագինացիա, կուրսորներ և սթրիմինգ

Express/iterator 'ծույլ ընդհատում, տրանզիցենտային սխալների ժամանակ։

Keyset-pagination 'կայուն կարգավորում «(contated _ at, id)»։

Backpressure: Միաժամանակ հարցումների սահմանափակում; в async-SDK — `async for`/`channels`.

Սթրիմինգը (որտեղ հասանելի է) 'SSE/Windows Socket/gRPC-stream' avto-reconnations և dedup '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`.

Best practice: հաղորդագրությունները մարդկային են, «error _ code» կայուն։

10) Լեզվական իդիոմներ

TypeScript/JS

Promise-based + երգեցողության գեներատորներ; ESM + CJS փաթեթներ։

Tree-shaking, նվազագույն պոլիֆիլներ, Abert-ազդանշաններ («Abert Systler»)։

Python

Disnc + Async (aiohttp/httpx), ենթատեքստային ղեկավարներ, «pydantic» մոդելներ (կամ medaclasses)։

Wheels для linux/macos/windows; աջակցություն proxies/CSO _ PROXY։

Java

«Completics Future» (անհրաժեշտության դեպքում), «Closeable», «Duration», «Executor»։

HTTP client: `java. net. http 'կամ OkHtp; SLF4.RU լոգոների համար։

Go

Համատեքստերը 'ext։ Context`, `http. Client 's tuned Transport-ից, թեստերի ինտերֆեյսներ։

Error wrapping (`fmt. Errorf ("% w", err) "), sentinel սխալների սեմանտիկան։

.NET

`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.

Poly (retry/circuit-breaker)։

... և այլն PHP/Ruby (PSR-18, Faraday/Net: HTTP) համար։

11) Տրամաբանություն, մետրեր, հետքեր

Լոգներ ՝ մակարդակներ (ERROR/WARN/MS/DEBUG), կորլացիա 'trace _ id ", զգայուն տվյալների անջատումը։

Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.

Հետքերը ՝ OpenTelemetry hooks (API-ի մարտահրավեր, endpoint, status, retry)։

Debug-mode: փոփոխական միջավայր 'GH _ MSK _ DEBUG = 1 "- HTTP վերնագրերի (առանց գաղտնիքների) և ժամանակների։

12) Մոսկվան և օրինակները

Quickstart 5 րոպե 'auth, առաջին հարցումը, պագինացիան, մշակումը 429։

Cookbook: webhuks (ստորագրության ստուգում), idempotent write, replay։

API-ի տեղեկատու 'OpenAPI/Eurobuf-ի ավտոգենը, բայց «ձեռքով» օրինակներով։

Syppets: կոդի պատրաստի կտորները հայտնի առաջադրանքների համար (Python/TS/Java/Go/.NET)։

13) vs-ի գեներացիան ձեռքով կոդավորում է

Համակցված մոտեցումը 'codegen (մոդելներ/հաճախորդներ) + ձեռքով «բռնակներ» ergonomator/idempotention/վնասատուների համար։

Ձևանմուշները 'մեթոդների միասնական անուններ ("create/get/list/delete/), 108։ ազդանշաններ։

«Diff-2019» ստուգումը ռեգենից հետո (CI-գեյթ)։

14) Տարբերակումը, համատեղելիությունը և դեպրեսիան

SemVer: X.Y.Z. լոկոմոտիվը միայն major է։

Կայունության քաղաքականությունը 'մինորական օրինագծերը ավելացնում են դաշտերը/մեթոդները, չեն փոխում պայմանագրերը։

Deprecation: in Deprecated/Obsolete-ը, նախազգուշացումները rantaime-ում մեկ անգամ գործընթացի ընթացքում, պատուհանը 90 օր։

LTS-ճյուղերը 'back.ru քննադատներ (առանց նոր ֆիչի)։

15) Ալյումինե և մատակարարման շղթա

CI/CD: ոսպնյակներ/արտադրողներ, unit + integration, պայմանագիր-թեստեր, e2e դեմ ավազի դեմ։

Արտեֆակտների ստորագրությունը 'Sigstore/GPG, www.ksums։

Հրապարակումը ՝ npm/PyPI/Maven/NuGet/Go/Composer/RubyGems 'changelog և releportnotes։

SemVer gate: Ռուսական հանրային API (օրինակ ՝ «apiregistry diff»)։

16) Փորձարկում (որակի մատրիցա)

Unit: Մոդելներ, սերիալիզացիա, վալիդացիա, ռետտա/թայմաուտներ։

Disract: OpenAPI/Eurobuf սխեմաների դեմ (negative/edge cases)։

Integration: sandbox-ի դեմ (idempotention, 429/5xx, webhooks)։

Load/soak: pagination/strim, backpressure։

Ֆուզզ 'դաշտեր/վերնագրեր/ժամանակի սահմաններ։

Compat: հին SDK-ն նոր API-ն է և հակառակը։

Smoke-pack: 5 րոպե, որպեսզի բռնի CI-ում։

17) Հեռուստատեսության և մասնագիտության քաղաքականությունը

Oporational-opt-in 'հավաքելով համախմբված metric MSK (տարբերակը, լեզուն, կարգավիճակները) առանց PII-ի։

Քրեյգ ՝ «telemetry: off 'anonymized' fox» (լռելյայն off/anonymized)։

Թափանցիկություն 'փաստաթղթավորել, թե ինչ և ինչու է պատրաստվում։ Եկեք դրոշը պաշտպանենք։

18) Արտադրողականություն և Ֆինոպս

Batching 'համախմբել փոքրիկ հարցումները։ սահմանափակել RPS; gzip/br.

ETag/If-None-Match պայմանական GET-ը։

Տնտեսական մոդելները 'ծույլ iterators-ը, փոխարենը բոլոր հիշողության մեջ։

Զուգահեռ '«max _ concurrency», որպեսզի ոչ «DDOSit» 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}`); }
}

Պագինատոր (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 (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-ն RTK-ով ՝ կրիտիկական ուղիներ 'fix ETA, կապի ջրանցքներ, մատրիցա (SDK no API)։

Issue templates: bug/feature/question, 71-triage լեզվով/տարբերակով։

Roadmap/labels: «good first issue», «help wanted».

Security policy: `SECURITY. md ', ազդանշանների մասին հայտարարելու համար, CVE-ը անհրաժեշտության դեպքում։

21) Chek-SPK որակի ցուցակը

• Մեկ սխալ մոդել («status», «error _ code», «trace _ id», «retriable»)։
• Timauts/retrai/jitter, հարգանք «Retry-After»։
• Idempotenty write, ավտոմատ «Idempotency-Key»։
• Պագինասիան կուրսոր է, ծույլ իտերատորներ/ստրիմներ։
• Webhair Verifier-ը HMAC/mTSA-ի և պապի հետ։
• ENV/դիզայներ/պարամետրեր։
• Տրամաբանություն/չափումներ/OTel-huki, debug ռեժիմը առանց գաղտնիքների։
• SemVer, դեպրեսիաներ 90 օր, LTS-ճյուղեր։
• Ամբողջական օրինակներ և Cookbook-ը հանրաճանաչ խնդիրներով։
• Հավասարության մատրիցը CI լեզուների միջև է։

22) Իրականացման պլանը (3 իտացիա)

1. MVP (2-3 շաբաթ) 'հիմնական Client, auth, 3-5 հիմնական endpoints, պագինացիա, մեկ սխալ մոդել, retrai/timauta; TS+Python.

2. Scale (3-5 շաբաթ) 'Java/Go/.NET, Webhant Verifier, write, hooks հեռուստաչափություն, OpenAPI մոդելների արտադրություն։

3. Մոսկվա (շարունակաբար) 'striming/SSE/gRPC, perf-օպտիմիզացիա, LMS ճյուղեր, ընդլայնված Cookbook, խմբակցությունների/դեպրեսիաների գործիքներ։

23) Mini-FAQ

Վերացնել ամեն ինչ կամ գրել ձեռքերով։

Ստեղծեք մոդելներ/հաճախորդներ, իսկ ergonomics (վնասատուներ, retrai, idempotention, հարմար ազդանշաններ) 'ձեռքով։

Արդյո՞ ք անհրաժեշտ է առանձին async-MSK։

В Python — да (`AsyncClient`); JS-ում լռելյայն է։ NET/Java - ասինխրոն մարտահրավերներ հնարավորության դեպքում։

Ինչպե՞ ս պահել լեզուների հավասարությունը։

Ֆիչի մատրիցա CI-ում, «գոտիների վրա» (TS no Py, Java no Go NET) և «ինչ-որ բան հետ է մնում»։

Արդյունքը

Ուժեղ PPK-ը միասնական մակերես է, հուսալի դեֆոլտներ և կանխատեսելի պայմանագրեր, որոնք բոլոր լեզուներով են։ Թույլ տվեք մշակողներին ապահով ապրանքներ «տուփից», հասկանալի սխալ մոդել, հարմար պագինացիա և վեբհուկի հավատացում, ավարտեք այն որակյալ փաստարկով և խիստ semver։ Այդ ժամանակ բյուջեները արագ կլինեն, աջակցությունը էժան է, իսկ էկոհամակարգը ՝ կայուն և մեծացված։