Referans-implementasiya

1) Məqsədlər, sərhədlər və prinsiplər

1. Protokolun/spekanın birmənalı şərhini verin.

2. Müstəqil uyğunluq yoxlamasını təmin edin.

3. Müştəri/server/webhook iş nümunələri təqdim edin.

4. İnteqrasiya və tətbiq xərclərini azaltmaq.

• RI maksimum performansa deyil, davranış düzgünlüyünə diqqət yetirir.
• Prod parametrlərinin minimum dəsti daxildir (TLS, loging, metrika, treysinq, limiter).
• Kommersiya/məhsul satışını əvəz etmir, lakin «aşağı keyfiyyət çubuğunu» təyin edir.

• Spec-first: həqiqət - spesifikasiyalarda (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• Deterministic & Testable: təkrar cavablar və fikstürlər.
• Docs-as-Code: hamısı VCS, kod və konformans testləri ilə bir versiyası.
• Portability: konteynerlər, Helm/compose, hazır manifestlər.

2) Referens-implementasiya növləri

RI-Server: spesifikasiyaya görə server etalonu (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: müştəri etalonu (bir-iki məşhur platforma) + nümunələr.
RI-Webhook Receiver: imzalanmış vebhuk prosessoru (imza yoxlaması, retralar).
RI-Adapters: mesaj brokerlərinə/hadisə şinlərinə adapterlər (Avro/Proto/JSON, Schema Registry).
RI-Data: istinad dəsti, məxfilik profilləri, «qızıl» snapshotlar.

3) RI anbarının arxitekturası

ri/
specs/# OpenAPI/AsyncAPI/Proto/JSON-Schema server/# reference server src/
config/
docker/
helm/
client/# reference client/SDK + examples js/python/go/
conformance/# conformance runner, test cases, gold cases files/
fixtures/
golden/
samples/# end-to-end scripts, Postman/k6/Locust security/# test keys, policies, example signature docs/# manual, ADR, runbook, FAQ ci/# pipelines, configs, compatibility matrix tools/# generators, linters, circuit checkers

• Hər buraxılış üçün 'vX etiketi. Y.Z 'və artefaktlar (şəkillər, çartlar, SDK).
• Hər bir tikmə üçün - məbləğ və imza (supply-chain).
• CHANGELOG «sındırıcı» dəyişikliklər (breaking) işarəsi ilə.

4) Specks, müqavilələr və sxemlər

Nəqliyyat: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
Semantika: səhv kodları, idempotentlik, kursorlar/paginasiya, retrajlar, deduplikasiya.
Hadisələr: növü/versiyası, 'id', 'occurred _ at _ utc', 'partition _ key', invariantları sifariş.
Siqnallar/Təhlükəsizlik: OIDC/JWT markaları, Webhook imzası (HMAC/EdDSA), açar rotasiyası.
Kompatibiliti sxemləri: 'backward' forward 'full' qaydaları, MAJOR olmadan pozucu dəyişikliklərin qadağan edilməsi.

5) Konformans testi

• spekulyasiyalara uyğunluq (sxemlərin validasiyası),
• davranış invariantları (idempotentlik, çeşidləmə, kursorlar, TTL, retry-siyasətlər),
• təhlükəsizlik (imzalar, şərtlər, nonce/replay-müdafiə),
• zaman aspektləri (UTC, RFC3339, DST),
• mənfi hallar və sərhəd şərtləri.

Qızıl fayllar (golden): nəticələrin müqayisə olunduğu sabit istinad cavabları/hadisələr.

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) Production minimum (heç bir artıqlıq)

Security: TLS by default, təhlükəsizlik başlıqları, CORS məhdudiyyəti, məhdudiyyətlər, anti-replay.
Observability: loqlar (struktur + maskalama PD), metriklər (p50/p95/p99, error rate), treysinq (korrelyasiya 'request _ id').
Config: Bütün dəyişən mühit və fayllar vasitəsilə, konfiqurasiya sxemi təsdiqlənir.
Perf-bazline: sağlam hovuz parametrləri, zəncirvari vaxt-büdcə, coalescing ilə cache.
Sabitlik: circuit breaker, backpressure.

7) CI/CD və artefaktlar

1. Lint/montaj/vahid testləri.

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

3. Spec SDK/stables Generation.

4. Konformans-ran: 'ri-server' qarşı 'cases' və «qızıl».

5. Şəkillərin toplanması (SBOM, imza), reyestrdə dərc edilməsi.

6. E2E ssenariləri (docker-compose/kind/Helm).

7. Dock saytı və nümunələrin yayımlanması.

• konteyner şəkilləri 'ri-server', 'ri-webhook',
• SDK paketləri (npm/pypi/go),
• Helm-chart/compose faylları,
• zip «qızıl fayllar» və konformans ranner ilə.

8) Samples, SDK və «how-to»

İki məşhur yığın (məsələn, Node. js/Go) addımları ilə: autentifikasiya → API çağırışı → səhv emalı → retraia → vebhuk.
How-to: İdempotent POST, kursor paginasiyası, vebhuk imzası, 429/503 emalı.
«smoke-perf» üçün k6/JMeter profillər (yük deyil, əsas sağlamlıq).

9) Version və təkamül

SemVer: sındırıcı dəyişikliklər → MAJOR; qırılmadan əlavə → MINOR; düzəlişlər → PATCH.
Deprecation-plan: Spekulyasiyalarda elanlar, fiça bayraqları, «kölgə» conformance rejimi dövrü, sonra enforce.
Hadisələrin uyğunluğu: konsumerlər naməlum sahələrə məhəl qoymamalıdırlar.

10) RI təhlükəsizlik və məxfilik

Test açarları və sirləri - yalnız stend üçün; doklarda - dəyişdirmə təlimatı.
Log PD maskalamaq; fikstura anonimləşdirmə profilləri (PII → sintetika).
Demo mühit artefaktlarının həyat vaxtı siyasəti (TTL, avtomatik təmizləmə).

11) RI üçün müşahidə və SLO

SLI/SLO RI: p95 <250 ms istinad stendində, error rate <0. 5%, asılılıq uğursuzluğu ilə düzgün deqradasiya (sempla).
Daşbordlar: latency/Throughput/Errors + konformans nəticələri.
WebHook imzası/token yoxlamaları üçün Decision-log (uğursuzluq səbəbləri).

12) Məhsuldarlıq: «kifayət qədər» bazline

«Isti» və «soyuq» yollarda 'wrk/hey/k6' profilləri.
Aydın mövqe: RI maksimum RPS ilə rəqabət etmir, lakin tipik hədəfə dözməlidir (məsələn, t3 üçün 500 RPS. p95 <200ms) ilə orta - inteqratorlar üçün istinad nöqtəsi kimi.

13) Manual əməliyyat (runbook)

Lokal başlanğıc: compose/' make up '.
K8s-deploy: Helm dəyərləri, sirləri, ingress, HPA.
Roteyshn vebhuk imza açarları (dual-key dövrü).
Trablshuting: tez-tez səhvlər və onların səbəbləri (401, 403, 429, 503), necə logi/treys oxumaq.

14) İdarəetmə və sahiblik

Owners: məhsul sahibi sink + platforma (texnika) + təhlükəsizlik.
Buraxılış təqvimi və pozucu dəyişikliklərin əlaqələndirilməsi pəncərəsi.
RFC/ADR əhəmiyyətli protokol dəyişiklikləri.

15) Dillərə/platformalara uyğunlaşma

Tövsiyə olunan minimum: bir yüksək səviyyəli (JS/TS) və bir sistem (Go/Java).
Mapping növləri: tarixlər/pul formatları/decimal/bayt dəstləri təqdim olunur.
Hər SDK-da retras/zaman/hovuz parametrləri üçün tövsiyələr.

16) Anti-nümunələr

RI = «testsiz qum qutusu»: heç bir rahatlıq, fayda yoxdur.
Speca kod və testlərdən «ayrı yaşayır» → uyğunsuzluq.
«Qızıl fayllar» və invariantların olmaması → fleyka və davranış mübahisələri.
Framework asılılığı: konteynerləşdirilmədən bir kitabxanaya/buludlara möhkəm bağlanma.
PD maskası olmadan log, anbarda açarlar.
Davranış əvəzinə Perf-mix: «Kim daha sürətli» əvəzinə «Kim doğru» ölçmək üçün cəhd.
Modulluq və artefaktlar olmadan bir nəhəng binar/görüntü (SDK/charts/species).

17) Memarın yoxlama siyahısı

1. Speca - kanonik və valid? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. Tam nümunələri olan bir RI-server və ən azı bir RI-client/SDK var?
3. Konformans ranner, cases, «qızıl fayllar», neqativlər və invariantlar hazırdır?
4. CI/CD şəkillər toplayır, SDK, site, conformance və e2e başlayır?
5. Təhlükəsizlik default: TLS, imzalar, Limiters, gizlətmə PD?
6. Müşahidə müddəti: RI üçün log/metrika/treys, dashboard və SLO?
7. Perf-bazline sənədləşdirilmiş və oynatmaq?
8. SemVer versiyası, uyğunluq matrisi, deprecation proseduru?
9. Runbook və lokal/klaster başlanğıc - bir klik?
10. Sahibləri, buraxılış təqvimi, RFC/ADR axını müəyyən?

18) Mini nümunə: referans-vebhuk (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

Test case yoxlayır: vaxt pəncərəsi, imza düzgünlüyü (cari və əvvəlki açar), idempotent 'event. id ', neqativlər (pozulmuş imza, vaxtı keçmiş' ts ').

Nəticə

Referens-implementasiya sistemin davranış kanonudur: kod, testlər və artefaktlarla təsdiqlənmiş vahid speck. Yaxşı RI inteqrasiyanı sürətləndirir, protokolların qeyri-müəyyənliyini aradan qaldırır, yoxlanıla bilən uyğunluğu təmin edir və minimum təhlükəsizlik, müşahidə və performans standartlarını təyin edir. Mühəndislik "skeleti 'nin bir hissəsi olun - və məhsullarınız, tərəfdaşlarınız və ekosisteminiz daha sürətli və daha etibarlı hərəkət edəcəkdir.