Referens-implementasiýa

1) Maksatlar, serhetler we ýörelgeler

1. Teswirnamanyň/synagyň birmeňzeş düşündirişini bermek.

2. Laýyklygyň garaşsyz barlagyny üpjün etmek.

3. Müşderi/serwer/webhook iş mysallaryny beriň.

4. Integrasiýalaryň we ornaşdyrmalaryň bahasyny arzanlatmak.

• RI iň ýokary öndürijilige däl-de, özüni alyp barşyň dogrulygyna ünsi jemleýär.
• Prod sazlamalarynyň iň az toplumyny öz içine alýar (TLS, logirleme, metrika, treýsing, limiterler).
• Täjirçilik/önüm satuwynyň ornuny tutmaýar, ýöne "hiliň aşaky çyzygyny" kesgitleýär.

• Spec-first: hakykat - spesifikasiýalarda (OpenAPI/AsyncAPI/Proto/JSON-Shema/IDL).
• Deterministic & Testable: gaýtalanýan jogaplar we fiksturlar.
• Docs-as-Code: VCS-de hemme zat, kod we konformans synaglary bilen bir wersiýa.
• Portability: konteýnerler, Helm/compose, taýýar manifestler.

2) Referens-implementasiýalaryň görnüşleri

RI-Server: spesifikasiýa boýunça serwer standarty (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: Müşderi standarty (bir ýa-da iki sany meşhur platforma) + mysallar.
RI-Webhook Receiver: Gol çekilen webhuklary işleýji (goly barlamak, retralar).
RI-Adapters: habar brokerlerine/waka tekerlerine adapterler (Euro/Proto/JSON, Schema Registry).
RI-Data: maglumat toplary, gizlinlik profilleri, "altyn" snapshotlar.

3) Reozoryň arhitekturasy 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/        # генераторы, линтеры, проверяльщики схем

• Her bir çykyşy 'vX tag. Y.Z 'we artefaktlar (şekiller, tertipler, SDK).
• Her bölek üçin - jemi we gol (supply-chain).
• "Döwýän" üýtgeşmeler (breaking) bilen CHANGELOG.

4) Spekler, şertnamalar we shemalar

Ulag: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
Semantika: ýalňyşlyk kodlary, idempotentlik, kursorlar/paginasiýa, retralar, de-duplikasiýa.
Wakalar: 'id', 'occurred _ at _ utc', 'partition _ key', sargyt üýtgemeleri.
Nyşanlar/howpsuzlyk: OIDC/JWT bellikleri, webhuk goly (HMAC/EdDSA), açarlaryň aýlanmagy.

5) Ylalaşyk synagy

• spekulýatorlara laýyklyk (shemalary tassyklamak),
• özüni alyp barşyň üýtgemegi (idempotentlik, sortlamak, kursorlar, TTL, retry-syýasatlar),
• howpsuzlyk (gollar, möhletler, nonce/replay-gorag),
• wagt taraplary (UTC, RFC3339, DST),
• negatiw ýagdaýlar we serhet şertleri.

Altyn faýllar (golden): netijeleriň deňeşdirilýän durnukly salgylanma jogaplary/wakalary.

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) Prodakşen-minimum (artykmaçlyksyz)

Howpsuzlyk: TLS by default, howpsuzlyk sözbaşylary, CORS çäklendirmeleri, çäklendirijiler, anti-replay.
Observability: loglar (gurluş + gizlemek PD), metrikler (p50/p95/p99, error rate), treýsing (korrelasiýa 'request _ id').
Config: daşky gurşaw üýtgeýjileri we faýllar arkaly, konfigurasiýa shemasy tassyklanýar.
Perf-bazline: howuzlary dogry sazlamak, zynjyr boýunça wagt-býudjet, coalescing bilen nagt pul.
Durnuklylyk: jitter, circuit breaker, backpressure bilen retrailer.

7) CI/CD we artefaktlar

1. Lint/ýygnamak/birlik synaglary.

2. Spec tassyklamasy (OpenAPI/AsyncAPI/Proto-lint).

3. Speclerden SDK/stabil döretmek.

4. Konformans-ran: 'ri-server' vs 'cases' we "altyn".

5. Şekilleri ýygnamak (SBOM, gol), reýestre çap etmek.

6. E2E ssenarileri (docker-compose/kind/Helm).

7. Dok-saýty we mysallary çap etmek.

• konteýner şekilleri 'ri-server', 'ri-webhook',
• SDK paketleri (npm/pypi/go),
• Helm-çart/compose-faýllar,
• zip "altyn faýllar" we konformans-ranner bilen.

8) Semplar, SDK we "how-to"

Iki sany meşhur äýnekdäki kiçi programma (mysal üçin, Node. js/Go) ädimleri bilen: tassyklamak → API çagyryşy → ýalňyşlyklary bejermek → retra → webhuk.
How-to: idempotent POST, kursor paginasiýasy, webhuk goly, gaýtadan işlemek 429/503.
"Smoke-perf" üçin k6/JMeter profiller (ýük däl, esasy saglyk).

9) Wersiýalaşdyrmak we ewolýusiýa

SemVer: üýtgetmek → MAJOR; | MINOR; düzedişler → PATCH.
Deprecation-plan: spekulýasiýa, ficha-baýdaklar, "kölegeli" conformance re modeiminiň döwri, soňra enforce.
Wakalaryň laýyklygy: konsumerler nätanyş meýdanlary äsgermezlik etmäge borçludyrlar.

10) RI-de howpsuzlyk we gizlinlik

Synag açarlary we syrlary - diňe stend üçin; doklarda - çalyşmagyň görkezmesi.
PD-ni bloglarda gizlemek; fikstura anonimleşdirme profilleri (PII → sintetika).
Demo-gurşaw artefaktlarynyň durmuş wagty syýasaty (TTL, awto-arassalamak).

11) RI üçin synlamak we SLO

SLI/SLO RI: p95 <250 ms standart stendde, error rate <0. 5%, garaşlylygyň ret edilmegi bilen dogry pese gaçmak (semplada).
Daşbordlar: latency/Throughput/Errors + konformans-netijeler.
Webhuklara gol çekmek/bellikleri barlamak üçin "Decision-logs" (şowsuzlygyň yzarlanylýan sebäpleri).

12) Öndürijilik: "ýeterlik" bazline

'wrk/hey/k6' profilleri "gyzgyn" we "sowuk" ýollarda.
Takyk pozisiýa: RI iň ýokary RPS boýunça bäsleşmeýär, ýöne adaty nyşana çydamaly (mysal üçin t3-de 500 RPS). medium s p95 <200ms) - integratorlar üçin görkeziji hökmünde.

13) Ulanyş gollanmasy (runbook)

Lokal başlangyç: compose/' make up '.
K8s-deploy: Helm bahalary, syrlar, ingress, HPA.
Webhuk gol açarlarynyň roteýşn (dual-key period).
Trablshuting: ýygy-ýygydan ýalňyşlyklar we olaryň sebäpleri (401, 403, 429, 503).

14) Dolandyrmak we eýeçilik etmek

Owners: önüm eýesi spek + platforma (tehnika) + howpsuzlyk.
Relizleriň senenamasy we bozýan üýtgeşmeleri utgaşdyrmak penjiresi.
RFC/ADR teswirnamalardaky möhüm üýtgeşmeler üçin.

15) Dillere/platformalara uýgunlaşmak

Teklip edilýän iň az: bir ýokary derejeli (JS/TS) we bir ulgam (Go/Java).
Mapping görnüşleri: seneler/pul formatlary/decimal/bayt toplumlary hödürlenilişi ýaly.
Her SDK-da retralar/wagtlar/howuz sazlamalary boýunça teklipler.

16) Anti-patternler

RI = "Synagsyz sandyk gutusy": hiç hili ylalaşyk, hiç hili peýdasy ýok.
Speka koddan we synaglardan "aýratyn ýaşaýar" → tapawut.
"Altyn faýllaryň" we üýtgemeleriň ýoklugy → fleýka we özüni alyp barşy baradaky jedeller.
Freýmwork-garaşlylyk: konteýnerizasiýa edilmezden bir kitaphana/bulut bilen berk baglanyşyk.
PD gizlenmezden girelgeler, ammarda açarlar.
Özüňi alyp barşyň ýerine perf-mix: "kim has çalt" ýerine "kim dogry" ölçemäge synanyşyň.
Modulsyz we artefaktsyz bir äpet binar/şekil (SDK/charts/speks).

17) Arhitektoryň çek-sanawy

1. Speka - kanoniki we tassyklanan? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. RI-serwer we iň bolmanda bir RI-client/SDK barmy?
3. "Konformans-ranner", "altyn faýllar", negatiwler we üýtgemeler taýýar?
4. CI/CD şekilleri, SDK, web sahypasyny ýygnaýar, conformance we e2e işe girizýärmi?
5. Howpsuzlyk: TLS, gollar, çäklendirijiler, gizlemek PD?
6. Syn edilişi: RI üçin loglar/metrikler/söwdalar, dashbordlar we SLO?
7. Perf-bazline resminamalaşdyryldy we köpeldilýärmi?
8. SemVer wersiýalamak, gabat gelmek matrisi, deprecation-prosedura?
9. Runbook we lokal/klaster - bir gezek basmak?
10. Eýeleri, goýberiş senenamasy, RFC/ADR akymy kesgitlenildi?

18) Mini-mysal: referens-webhuk (psevdokod)

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

Synag-keýs: wagt penjiresini, goluň dogrulygyny (häzirki we öňki açary), 'event. id ', negatiwler (bozulan gol, möhleti geçen' ts ').

Netije

Referens-implementasiýa - ulgamyň özüni alyp barşynyň kanonydyr: kod, synaglar we artefaktlar bilen tassyklanan ýekeje spek. Gowy RI integrasiýany çaltlaşdyrýar, teswirnamalaryň düşnüksizligini aýyrýar, barlanylýan laýyklygy üpjün edýär we iň pes howpsuzlyk, gözegçilik we öndürijilik standartlaryny kesgitleýär. Ony in engineeringenerçilik "skeletiňiziň" bir bölegine öwüriň - önümleriňiz, hyzmatdaşlaryňyz we ekosistemaňyz has çalt we ygtybarly hereket eder.