Հանրաքվե-իմպեմենտացիա

1) Նպատակներ, սահմաններ և սկզբունքներ

Նպատակները

1. Տվեք արձանագրության/մեջքի միանշանակ մեկնաբանություն։

2. Ապահով ստուգում տրամադրելու համար։

3. Տրամադրել հաճախորդի/սերվերի/վեբհուկի աշխատանքային օրինակներ։

4. Նվազեցնել ինտեգրման և ներդրման արժեքը։

Սահմանները

RI-ն կենտրոնանում է վարքագծային ճկունության վրա, ոչ թե արտադրողականության բարձրացման վրա։

Այն ներառում է նվազագույն prod-105 (TFC, լոգոն, մետրեր, թրեյսինգ, լիմիտերներ)։

Չի փոխարինում առևտրային/ապրանքային իրականացումը, բայց տալիս է «որակի ստորին պլանը»։

Սկզբունքները

Spec-first: Ճշմարտությունը մասնագիտություններում (OpenAPI/AsyncAPI/Delo/JSON-Schema/IDL)։

Deterministic & Testable: վերարտադրված պատասխանները և ֆիքսուրները։

Docs-as-Code: Ամեն ինչ VCS-ում, մեկ տարբերակ կոդով և կոնֆորմացիոն թեստերով։

Portability: բեռնարկղեր, Helm/compose, պատրաստի մանիֆեստներ։

2) Հանրաքվեների իմպեմենտացիայի տեսակները

RI-Server: սերվերի ստանդարտ (REST/gRPC/GraphQL/Streaming)։

RI-Client/MSK 'հաճախորդի ստանդարտ (մեկ-երկու հայտնի պլատֆորմներ) + օրինակներ։

RI-Webhook Receiver-ը ստորագրված Webhuks-ի վերարտադրողն է (ստորագրության հավատարմագրում, retray)։

RI-Adapters: Brockers/իրադարձությունների (Avro/Delo/JSON, Schema Registry)։

RI-International: Տվյալների ստանդարտ հավաքածուներ, գաղտնիության պրոֆիլներ, «ոսկե» սարքավորում։

3) RI ռեպոզորիայի ճարտարապետությունը

Առաջարկվող կառուցվածքը

ri/
specs/        # OpenAPI/AsyncAPI/Proto/JSON-Schema server/       # эталонный сервер src/
config/
docker/
helm/
client/       # эталонный клиент/SDK + примеры js/ python/ go/
conformance/     # конформанс-раннер, тест-кейсы, золотые файлы cases/
fixtures/
golden/
samples/       # end-to-end сценарии, Postman/k6/Locust security/      # ключи тестовые, политики, пример подписи docs/        # руководство, ADR, runbook, FAQ ci/         # пайплайны, конфиги, матрица совместимости tools/        # генераторы, линтеры, проверяльщики схем

Համաձայնագրեր

Յուրաքանչյուր թեգը 'vX։ Y.Z "և արտեֆակտները (պատկերներ, գծապատկերներ, MSK)։

Յուրաքանչյուր հետևի համար գումարը և ստորագրությունը (supply-chain)։

CHANGELOG-ը '«կոտրող» փոփոխությունների նշումով (breaking)։

4) Սպեկեր, պայմանագրեր և սխեմաներ

Տրանսպորտը ՝ OpenAPI/REST, gRPC/Delo, GraphQL DRL, AsyncAPI։

Սեմանտիկան 'սխալներ, գաղափարախոսություն, կուրսորներ/պագինացիաներ, ռեթրատիա, դեդուպլիկացիա։

Իրադարձությունները 'տեսակը/տարբերակը, «id», «occurred _ at _ utc», «partection _ key», կարգի ինվարանտներ։

Ազդանշաններ/անվտանգություն ՝ OIDC/JWT կլեյմա, վեբհուկի ստորագրություն (HMAC/EddDSA), կոդավորման։

5) Կոնֆորմանսի փորձարկումը

Ի՞ նչ ենք ստուգում

specam (սխեմաների վալիդացիա),

վարքագծային invariants (idempotention, տեսակավորում, կուրսորներ, TTL, retry քաղաքականություն),

անվտանգություն (ստորագրություններ, ժամկետներ, nonce/replay-պաշտպանություն),

ժամանակավոր ասպեկտներ (UTC, RFC339, DST),

բացասական դեպքեր և սահմանափակում պայմաններ։

Ոսկե ֆայլերը (golden) 'կայուն ստանդարտ պատասխաններ/իրադարձություններ, որոնց դեմ համեմատվում են արդյունքները։

Sketch ranner

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case.input)
res = http_call(target_url, req)
assert match_status(res.status, case.expect.status)
assert match_headers(res.headers, case.expect.headers)
assert match_body(res.json, golden_dir / case.id, allow_extra_fields=True)
for invariant in case.invariants:
assert invariant.holds(res, case.context)

Մատրիցա (օրինակ)

consumer/sdk-js 1.4server 1.6, 1.7server 2.0 consumer/sdk-go 0.9server 1.5–1.7   –
webhook-receiver 1.1events v1events v2 (deprecated fields removed)

6) Prodacchen-նվազագույն (առանց բուժումների)

Տե՛ ս ՝ TRS by-ը, անվտանգության վերնագրերը, MSS-ի սահմանափակումը, սահմանաչափերը, հակա-replay-ը։

Observability: Logs (կառուցվածքային + PD), մետրիկները (p50/p95/p99, error rate), թրեյսինգը (հարաբերակցությունը 'request _ id ")։

Express: Ամեն ինչ շրջակա միջավայրի և ֆայլերի միջոցով, կազմաձևման սխեման վալիդացվում է։

Perf-bunline: փամփուշտների առողջ իրականացումը, շղթայի թայմաութ բյուջեն, coalescing-ի քեշը։

Իսպանիան 'ջիթերի, circuit breaker, backpressure։

7) CI/CD և արտեֆակտներ

Դելպլին (հանրաքվեներ)

1. Լինթ/հավաքում/յունիտների թեստեր։

2. (OpenAPI/AsyncAPI/Into-lint)։

3. SDK/Express գեներացիան մեջքից։

4. Կոնֆորանսը '"ri-server' ընդդեմ" cases "և" ոսկու "։

5. Պատկերների հավաքումը (SBSA, ստորագրություն), հրատարակումը խմբագրությունում։

6. E2E սցենարները (docker-compose/kind/Helm)։

7. Դոկ կայքի և օրինակների հրապարակումը։

Արտեֆակտները։

բեռնարկղային պատկերներ «ri-server», «ri-webhook»,

MSK փաթեթներ (npm/pypi/go),

Helm-chart/compose ֆայլեր,

zip-ը «ոսկե ֆայլերով» և կոնֆորմանսային ռեների հետ։

8) Սեմպլները, MSK և «how-to»

Մինի-ծրագիրը երկու հայտնի ապակիների վրա (օրինակ ՝ Node։ js/Go) քայլերով 'API-ի զանգի վավերացումը բացատրում է սխալների վերամշակում։

How-to 'idempotent POST-ը, կուրսային սագինացիան, վեբհուկի ստորագրությունը, 429/503 վերամշակումը։

k6/JMeter-ը ավելացված է «smoke-perfa» (ոչ թե ռուսական, այլ առողջ) համար։

9) Տարբերակումը և էվոլյուցիան

SemVer: կոտրող փոփոխություններ MAJOR-ում; ավելացում առանց կոտրվածքի MINOR; ուղղումներ PATCH։

Deprecation-պլանը 'հայտարարությունները սպեկերում, ֆիչի դրոշներում, www.orm.ru-ի «ստվերային» ռեժիմի ժամանակահատվածը, ապա enforce-ը։

Իրադարձությունների համատեղելիությունը 'վահանակները պարտավոր են անտեսել անծանոթ դաշտերը։

10) Անվտանգությունն ու սեփականաշնորհումը RI-ում

Թեստային բանալիները և գաղտնիքները միայն պատի համար են։ դանակներում փոխարինման հրահանգն է։

PD-ի դիմակավորում լոգարաններում։ ֆիքսթուրների անանունացման ավելցուկը (PII intintephics)։

Դեմո միջավայրի արտեֆակտների կյանքի քաղաքականությունը (TTL, Auto-մաքրումը)։

11) Դիտարկումը և SLO-ն RI-ի համար

SLI/SLO RI: p95 <250 ms ստանդարտ պատի վրա, error rate <0։ Հինգ տոկոսը, ճիշտ դեգրադացիան կախվածության հրաժարման տակ (սեմպլում)։

Dashbords: latency/Throughput/Errors + կոնֆորմացիոն արդյունքները։

Decision-Logs-ը ստորագրելու համար webhuks/Toxen ստուգումներ (ձախողումների հետադարձելի պատճառները)։

12) Արտադրողականություն ՝ «բավարար» բազլայնը

Ավելցուկ 'wrk/hey/k6 «տաք» և «սառը» ճանապարհների վրա։

Պարզ դիրք. RI-ը չի մրցում առավելագույն RPS-ով, բայց պետք է դիմակայի տիպիկ target (օրինակ ՝ 500 RPS t3։ R95 <200ms) - որպես ինտեգրատորների ուղեցույց։

13) Գործողության ղեկավարությունը (runbook)

Տեղական գործարկումը 'compose/« make up »։

K8s-depla: Helm արժեքներ, գաղտնիքներ, ingress, HPA։

Քրեյշնը բացատրում է վեբհուկի ստորագրությունները (dox-key ժամանակահատվածը)։

Trablshuting: հաճախակի սխալներ և պատճառներ (401, 403, 429, 503), ինչպես կարդալ logs/treiss։

14) Կառավարությունն ու ունեցվածքը

Owners 'սպեկտրի ապրանքային սեփականատերը + պլատֆորմը (տեխնոլոգիան) + անվտանգությունը։

Օրինագծերի օրացույցը և կոտրող փոփոխությունների հաստատման պատուհանը։

RSA/ADR-ը նշանակալի փոփոխությունների վրա։

15) Հարմարեցում լեզուների/պլատֆորմի համար

Առաջարկվող նվազագույն ՝ մեկ բարձր մակարդակի (JS/TS) և մեկ համակարգային (Go/Java)։

Mapping տեսակի. Ինչպես են ներկայացված ամսաթվերը/դրամական կոդերը/decimal/բայթերի հավաքածուները։

Ռելեների/թայմաուտների/պուլային պարամետրերի առաջարկությունները յուրաքանչյուր SDK-ում։

16) Anti-patterna

RI = «ավազը առանց թեստերի» 'չկա կոնֆորմացիա, ոչ էլ օգուտներ։

Սպան «ապրում է առանձին» կոդից և թեստերից բացատրվում է անհամապատասխանությունը։

«Ոսկե ֆայլերի» և ինվարանտների բացակայությունը ռուսական ֆլեյկի և վարքի մասին բանավեճերի մասին։

Ֆրեյմորքի կախվածությունը 'խիստ կապվածություն մեկ գրադարանի/ամպերի հետ առանց տարանջատման։

Լոգները առանց PD-ի դիմահարդարման, բանալիներ են։

Փերֆ-խառնուրդները վարքի փոխարեն 'փորձելով չափել «ով ավելի արագ» փոխարեն «ով է ճիշտ»։

Մեկ հսկա բինար/պատկեր առանց մոդուլիզմի և արտեֆակտների (MSK/charts/spects)։

17) Ճարտարապետի չեկի թերթիկը

1. Սպեկան կանոնական և վալիդացված է։ (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. Կա RI-server և առնվազն մեկ RI-client/MSK-ը ամբողջական օրինակներով։

3. Կոնֆորմանս-ռաններ, քեյսներ, «ոսկե ֆայլեր», բացասական և ինվարիացիաներ պատրաստ են։

4. CI/CD-ն հավաքում է պատկերներ, SDK, կայքը, սկսում է www.orm.ru և e2e։

5. Լռելյայն անվտանգությունը 'TFC, ստորագրություններ, սահմաններ, PD դիմակավորում։

6. Դիտարկումը 'logs/metrics/treiss, dashbords և SLO RI-ի համար։

7. Perf-բազլայնը փաստաթղթավորված և վերարտադրված է։

8. SemVer-ի տարբերակումը, կոդավորման մատրիցը, deprecation-ընթացակարգը։

9. Runbook-ը և տեղական/կլաստերային արձակումը 'մեկ կտոր։

10. Սեփականատերերը, օրինագծերի օրացույցը, RFC/ADR հոսքը որոշված են։

18) Մինի-օրինակ 'Webhuk (կեղծ)

python def verify_webhook(request, keys):
sig = request.headers["X-Signature"]
ts = int(request.headers["X-Timestamp"])
if abs(now_utc().epoch - ts) > 300: return 401 # replay window body = request.raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys.active_and_previous()):
return 401 event = json.loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

Թեստ-Քեյսը ստուգում է, որ ժամանակի պատուհանը, ստորագրության ճկունությունը (ընթացիկ և նախորդ բանալին), գաղափարախոսությունը 'event։ id ', բացասական (կոտրված ստորագրություն, ժամկետանց' ts ')։

Եզրակացություն

Հանրաքվեը համակարգի վարքագծի կանոնն է, որը հաստատվում է կոդով, թեստերով և արտեֆակտներով։ Լավ RI-ն արագացնում է պարամետրերը, մաքրում պարամետրերի երկիմաստությունը, ապահովում է ստուգված համատեղելիություն և տալիս անվտանգության, դիտարկման և արտադրողականության նվազագույն ստանդարտներ։ Դարձրեք այն ձեր ինժեներական կմախքի մի մասը, և ձեր ապրանքները, գործընկերները և էկոհամակարգը ավելի արագ և ավելի հուսալի կլինեն։