Protocol-first dizayn

Protocol-first nədir

Protocol-first - komponentlər (xidmətlər, müştərilər, xarici tərəfdaşlar) arasında qarşılıqlı əlaqə müqaviləsinin həyata keçirilmədən əvvəl layihələndirildiyi və qeydə alındığı yanaşmadır. Kod, anbarlar, infrastruktur və sənədlər müqaviləyə tabedir və avtomatik olaraq ondan yaranır, əksinə deyil.

API-nin yalnız kod yan məhsulu olduğu «code-first» -dən fərqli olaraq, Protocol-first protokolu ilkin artefakt edir: domen anlayışları, data modelləri, statuslar, səhvlər, idempotentlik semantikası, SLO/SLI və hətta versiya siyasəti.

Niyə lazımdır

Təşkilatın miqyasında interfeyslərin uyğunluğu və proqnozlaşdırılması.
Sürətli bağlama (SDK/stab/müştərilərin avtomatik generasiyası, vahid səhvlər və kodlar).
Etibarlı təkamül (sxemlərin uyğunluğu, müqavilə testləri, dəqiq versiya siyasəti).
Məhsul fokusu: kodun yazılmasından əvvəl davranış, SLA və UX inteqrasiyasını müzakirə edirik.
Avtomatlaşdırma: CI/CD bir həqiqət mənbəyindən artefaktları (müştərilər, serverlər, validatorlar) toplayır.
Təhlükəsizlik və uyğunluq: hüquqlar, PII maskalanması, retensiya siyasəti müqavilədə təsbit edilmişdir.

Yanaşma nüvəsi

1. Vahid Həqiqət Mənbəyi (SSOT) - maşınla oxunan spesifikasiyalar:

REST: OpenAPI/JSON Schema.
Hadisələr və axın: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + direktivlər/siyasətlər.
2. Həyata keçirilməzdən əvvəl razılaşmalar: domen sözlüyü, səhv kodları, idempotentlik semantikası, müddətlər, retraylar, deduplikasiya.
3. Avtogenerasiya: müştərilər/server yığınları, tiplər, SDK, müqavilə-testlər, moki, Postman-kolleksiyaları, Terraform/OpenAPI Gateway- .
4. Governance: linters/siyasətlər (naming, pagination, filtreler, səhvlər), API Guild vasitəsilə review, major versiyası üçün change-advisory.
5. Uyğunluq: ciddi yoxlama «additive-only» diffs, semantik version, canary/consumer-driven testlər.
6. Müqavilə səviyyəsində müşahidə: korrelyasiya ID, səhv modelləri, gecikmə büdcələri protokolda göstərilib.

Proses necə görünür (skelet)

1. Başlanğıc: məhsul brifi → user journeys → API/Protocol PRD (resurslar/metodlar/hadisələr, SLA/SLO, səhvlər, limitlər).
2. Modelləşdirmə: layihə spesifikasiyası (OpenAPI/AsyncAPI/Proto) + verilənlər sxemləri, terminlər lüğəti.
3. Müqavilələr və UX inteqrasiya: yük nümunələri, səhv müqavilələri, status kartları, version qaydaları.
4. Review və governance: linters/standartlar, domen invariantları müzakirə, MGC (minimum zəmanət müqaviləsi) kilidi.
5. Artefaktların avtogenerasiyası: SDK, stablar, test fiksturları, infrastruktur qapıları (Gateways, IAM scopes).
6. Realizasiya və müqavilə testləri: təchizatçı və istehlakçılar CI-də uyğunluq testindən keçir.
7. Müşahidə və SLO: correlation-id, error catalog, retrai/taymaut büdcələri ilə izləmə.
8. Relizlər və təkamül: additive-first, deprecation policy, canary, A/B capability flags.

Qarşılıqlı əlaqə protokolları və üslubları

REST/HTTP

Standartlar: resurs modeli, 'GET/POST/PATCH/DELETE', paginasiya (cursor), filtrlər, çeşidləmə.
Sahələr və sxemlər: JSON Sxema, formatlar ('date-time', 'uid'), invariantlar (regex/enum/min-max).
Səhvlər: vahid format ('type', 'code', 'title', 'detail', 'trace _ id'), HTTP yığınlarında mappinq.
Dəyişikliklərə nəzarət: ETag/If-Match, POST üçün idempotent açarları, 409/422 eksplisit semantiklər.

gRPC/RPC

Protobuf: etiketlərin sabit nömrələnməsi, 'optional', uzaq sahələrin yenidən istifadəsinin qadağan edilməsi.
Deadlines və müqavilədə prioritetlər; sabit statuslar (OK, INVALID_ARGUMENT, FAILED_PRECONDITION və s.).
Streaming: mesaj sırası, backpressure, son treyler spesifikasiyası.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: mövzular/kanallar, partizan açarları, deduplikasiya açarları, retensiya, semantika «düz bir dəfə» vs «ən azı bir dəfə».
Hadisə-nüvəsi və zənginləşdirilməsi: minimum payload və genişləndirmə paylaşın; 'event _ type '/' schema _ version' versiyası.
İdempotentlik: 'event _ id', 'producer _ id', retras və deduplikasiya policy.

GraphQL

Müqavilə kimi SDL, deprekeyt direktivləri, dərinlik və çətinlik limitləri, səhv müqaviləsi (error codes/extensions).

Memarlıq prinsipləri ilə inteqrasiya

Inverse Pyramid/Critical Path First: spesifikasiyada MGC (məcburi minimum), genişləndirmələr - vasitəsilə 'include = '/capabilities.
Paved Roads: hazır spesifikasiya şablonları (payment, KYC, audit, search, files) + linterlər.
API Gateways & Service Mesh: müqavilə əsaslı siyasətlər (rate-limits, auth scopes, retries, circuit-breakers).

Version və təkamül

• Minor = yalnız əlavə sahələr/kanallar.
• Major = pozucu dəyişikliklər (silmə, ad dəyişdirmə, semantika dəyişikliyi).
• Deprecation Policy: dəstək pəncərələri, «Sunset» başlıqları, bildiriş tədbirləri.
• Consumer-Driven Contracts (CDC): Cari API-nin konkret istehlakçıları qane etdiyini yoxlayın.
• Sxemlər kataloqu: tarixi və uyğunluq qaydaları olan reyestr (Schema Registry/Artifact Registry) (BACKWARD/FORWARD/FULL).

Təhlükəsizlik və uyğunluq

Müqavilənin bir hissəsi kimi autentifikasiya/avtorizasiya (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: maskalama, tokenizasiya formatları, xüsusi saxlama rejimləri olan sahələr/TTL.
Audit siyasəti: məcburi atributlar ('actor', 'subject', 'action', 'occurred _ at', 'trace _ id').
Limitlər: rate limit headers, kvotalar, mesajların ölçüləri, müddətlər.

Müqavilə üzrə müşahidə

Correlation/Request-ID: spesifikasiyada tələb olunur.
Error Catalog: kodların sabit siyahısı və SLA aradan qaldırılması.
SLI/SLO: p50/p95 latency, uğurlu cavabların payı, uyğun hadisələrin payı, idempotent təkrarların payı.

Test və keyfiyyət

Contract tests (istehlakçı təchizatçısı), CI-də schema diff, mok serverlərinin yaradılması.
Golden samples: sorğuların/cavabların istinad nümunələri, e2e üçün fikstürlər.
Chaos/latency injection: MGC saxlayarkən zaman/retraut yoxlama, uzantıların deqradasiyası.

Nümunəvi domen şablonları

Ödəniş (REST + hadisələr)

'POST/payments' → '201 Created' s 'payment _ id', 'status = authorized'.
Hadisə 'payment. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
'payment. enriched. v1 ': risk-skor, geo, device-fingerprint.
Səhvlər: '422' (validasiya), '402' (payment required), '409' (duplicate).
SLA: avtorizasiya ≤ 800ms p95; 2s lag p95 ≤ nüvə hadisəsi.

KYC (gRPC + növbələr)

RPC `StartVerification(user_id)` → `operation_id`.
«kyc» topikasında irəliləyiş hadisələri. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Müqavilə PII sahələrini, saxlama müddətini, maskalanmasını, səbəb uğursuzluq kodlarını nəzərdə tutur.

Audit (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Zənginləşdirmə: IP, device, geo - ayrı bir hadisə/axın, nüvəni bloklamır.

Alətlər və avtomatika (təqribən yığın)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Gateway: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Reyestr: Sxemlərin Git kataloqu + Schema Registry/Artifact Registry.
Sənədləşmə: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-nümunələr

Code-first by accident: «ilk MVP nəzarət», post-faktum spesifikasiyası, sənədləşmə və davranış uyğunsuzluğu.
Swagger-wash: real qaydalar olmadan rəsmi OpenAPI (səhvlər, limitlər, SLA, versiyalar).
Uyğunluq pozulması: sahə silindi/major versiyası olmadan növü dəyişdirildi; protobuf etiketlərinin yenidən istifadəsi.
«Qalın» paginasiya/filtr olmadan cavab; idempotentliyin olmaması.
Təhlükəsizlik müqaviləsi: auth/Scopes wiki təsvir, lakin spesifikasiya deyil.

Prosesin təşkili ilə əlaqə

API Guild: qəyyumlar standartları, review dəyişikliklər, təlim.
Design Docs: hər bir API üçün - PRD, ADR (həllər), SLA, risk matrisi.
Change Management: RFC prosesi, release notes, miqrasiya qaydaları, deprecation-time line.
Paved Road & Templates: spesifikasiyadan xidmət çərçivələrinin generatorları (hendler skeleti, validasiya, log).

Çek vərəqləri

Başlamazdan əvvəl

• PRD və domen sözlüyü var.
• Seçilmiş üslub (REST/gRPC/Event/GraphQL) və sxem formatı.
• MGC, səhvlər, SLA/SLO, idempotentlik qaydaları müəyyən edilmişdir.

İnkişaf

• Specification linters və review keçir.
• SDK/stabillər/fikstür avtomatik generasiya konfiqurasiya.
• Müqavilə testləri (CDC) CI-yə daxildir; schema-diff uyğun olmayan dəyişiklikləri bloklayır.

Buraxılışdan əvvəl

• Nümunələr və səhv kodları ilə inteqratorlar üçün sənədləşdirmə.
• Müqavilə üzrə müşahidə: correlation-id, error catalog, SLI daşbordları.
• Version siyasəti və deprecation elan.

FAQ

Protocol-first API-first-dən nə ilə fərqlənir?
Çox vaxt terminlər sinonim kimi istifadə olunur. Protocol-first altında bu məqalədə biz müqavilənin sərtliyini və SLA, təhlükəsizlik və müşahidə də daxil olmaqla bütün stillərin (REST/RPC/Events/GraphQL) əhatə dairəsini vurğulayırıq.

Bu inkişafı yavaşlatmayacaqmı?
Başlanğıc bir az daha uzun ola bilər, lakin sonra inteqrasiya, sabitlik və paralel inkişaf sürətlərində (avtogenerasiya, sabit SDK) qalib gəlirik.

Sürətli təcrübələrlə nə etmək lazımdır?
Sxemlərin «kobud» versiyalarından (draft), feature flags və qum qutularından istifadə edin, lakin linterləri və əsas uyğunluq qaydalarını qaçırmayın.

Yekun

Protocol-ilk dizayn müqaviləni memarlıq mərkəzi edir: davranışı əlaqələndiririk, sxemləri düzəldir, generasiya və testləri avtomatlaşdırırıq, əlavə olaraq inkişaf edirik. Nəticədə proqnozlaşdırıla bilən inteqrasiyalar, yüksək inkişaf sürəti və sistemlərin miqyaslı və komandadakı dəyişikliklərə davamlılığı əldə edirik.