Protocol-first dizaýny

Protocol-first näme

Protocol-first, komponentleriň (hyzmatlaryň, müşderileriň, daşarky hyzmatdaşlaryň) arasyndaky özara gatnaşyk şertnamasynyň durmuşa geçirilmezden ozal işlenip düzülen we kesgitlenýän çemeleşmesidir. Kod, ammar, infrastruktura we resminamalar şertnama tabyn edilýär we tersine däl-de, awtomatiki usulda ondan emele gelýär.

API-iň diňe kod önümi bolan "kode-first" -den tapawutlylykda, Protocol-first protokoly esasy artefakt edýär: domen düşünjelerine, maglumat modellerine, statuslara, ýalňyşlyklara, idempotentlik semantikasyna, SLO/SLI we hatda wersiýa syýasatyna degişlidir.

Näme üçin gerek?

Guramanyň geriminde interfeýsleriň utgaşdyrylmagy we öňünden aýdyp boljakdygy.
Çalt konbording (SDK/stabilleriň/müşderileriň awtogenerasiýasy, ýeke-täk ýalňyşlyklar we kodlar).
Ygtybarly ewolýusiýa (shemalaryň laýyklygy, şertnama-synaglar, wersiýalaryň anyk syýasaty).
Önüm fokusy: kod ýazmazdan ozal özüni alyp barşyny, SLA we UX integrasiýasyny ara alyp maslahatlaşýarys.
Awtomatlaşdyryş: CI/CD hakykatyň bir çeşmesinden artefaktlary (müşderiler, serwer bloklary, tassyklaýjylar) ýygnaýar.
Howpsuzlyk we laýyklyk: hukuklar, PII-ni gizlemek, retensiýa syýasaty şertnamada berkidilýär.

Çemeleşmäniň özeni

1. Ýeke-täk hakykat çeşmesi (SSOT) - maşyn okalýan aýratynlyklar:

REST: OpenAPI/JSON Schema.
Wakalar we akym: AsyncAPI, Euro/JSON Shema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + direktiwalar/syýasatlar.
2. Durmuşa geçirmezden öňki ylalaşyklar: domen sözlügi, ýalňyşlyk kodlary, idempotentlik semantikasy, möhletler, retraýlar, deduplikasiýa.
3. Awtogenerasiýa: müşderiler/serwer bazalary, görnüşleri, SDK, şertnama-synaglar, moki, Postman-kolleksiýalary, Terraform/OpenAPI Gateway- .
4. Governance: linterler/syýasatlar (naming, paginasiýa, süzgüçler, ýalňyşlyklar), API gildiýasynyň üsti bilen gözden geçirmek, esasy wersiýalar üçin change-advisory.
5. Gabat gelmek: "additive-only" diffleri berk barlamak, semantik wersiýa, canary/consumer-driven synaglary.
6. Şertnama derejesinde syn edilmegi: korrelýasiýa şahsyýetnamasy, ýalňyşlyklaryň modelleri, gijikdirmeleriň býudjetleri teswirnamada ýazylýar.

Prosesiň görnüşi (skelet)

1. Başlangyç: önüm brifi → user journeys → API/Protocol PRD (çeşmeler/usullar/wakalar, SLA/SLO, ýalňyşlyklar, çäkler).
2. Modellemek: Aýratynlyklaryň taslamasy (OpenAPI/AsyncAPI/Proto) + maglumat shemalary, terminleriň sözlügi.
3. Şertnamalar we UX integrasiýasy: peýdaly ýüküň mysallary, ýalňyşlyklaryň şertnamalary, status kartalary, wersiýalaşdyrmagyň düzgünleri.
4. Revew we governance: linterler/standartlar, domen üýtgemelerini ara alyp maslahatlaşmak, lock-in MGC (iň az kepillik şertnamasy).
5. Artefaktlaryň awtogenerasiýasy: SDK, bloklar, synag fiksturalary, infrastruktura bloklary (Gateways, IAM scopes).
6. Satuw we şertnama-synaglar: üpjün ediji we sarp edijiler CI-de laýyklyk barlagyndan geçýärler.
7. Syn edilişi we SLO: correlation-id, error catalog, retraew/taymaut býudjetleri.
8. Neşirler we ewolýusiýa: additive-first, deprecation policy, canary, A/B capability flags.

Özara gatnaşyk protokollary we stilleri

REST/HTTP

Standartlar: çeşme modeli, 'GET/POST/PATCH/DELETE', paginasiýa (cursor), süzgüçler, sortlamak.
Meýdanlar we shemalar: JSON Shema, formatlar ('date-time', 'uuid'), inwariantlar (regex/enum/min-max).
Hatalar: ýeke-täk format ('type', 'code', 'title', 'detail', 'trace _ id'), HTTP stakynda mapping.
Üýtgeşmelere gözegçilik etmek: ETag/If-Match, POST üçin duýgur açarlar, 409/422.

gRPC/RPC

Protobuf: bellikleri yzygiderli sanamak, 'optional', uzakdaky meýdanlary gaýtadan ulanmagy gadagan etmek.
Şertnamadaky deadlines we ileri tutulýan ugurlar; durnukly statuslar (OK, INVALID_ARGUMENT, FAILED_PRECONDITION, etc.).
Streaming: habar tertibiniň aýratynlygy, backpressure, soňky trailer.

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

AsyncAPI: mowzuklar/kanallar, partizasiýa açarlary, duplikasiýa, retensiýa, semantika "takmynan bir gezek" vs "iň bolmanda bir gezek".
Esasy we baýlaşdyryş çäresi: iň az töleg we giňeltmek; 'event _ type '/' schema _ version' wersiýasy.
Idempotentlik: 'event _ id', 'producer _ id', retralar we duplikasiýa boýunça syýasat.

GraphQL

SDL şertnama, deprekeýt üçin görkezmeler, çuňluk we kynçylyk çäkleri, ýalňyşlyk şertnamasy (error codes/extensions) hökmünde.

Binagärlik ýörelgeleri bilen integrasiýa

"Inverse Pyramid/Critical Path First": aýratynlykda MGC (hökmany minimal), giňeltmek - "? include = '/capabilities arkaly.
Pawed Roads: taýýar spesifikasiýa şablonlarynyň toplumy (payment, KYC, audit, search, files) + linterler.
API Gateways & Service Mesh: şertnama esasly syýasatlar (rate-limits, auth scopes, retries, circuit-breakers).

Wersiýalaşdyrmak we ewolýusiýa

• Minor = diňe goşmaça meýdanlar/kanallar.
• Major = döwýän üýtgeşmeler (aýyrmak, adyny üýtgetmek, semantikany üýtgetmek).
• Deprecation Policy: goldaw penjireleri, "Sunset" sözbaşylary, habar beriş wakalary.
• Consumer-Driven Contracts (CDC): Häzirki API-iň belli bir sarp edijileri kanagatlandyrýandygyny barlaýarys.
• Shemalaryň katalogy: taryhy we laýyklyk düzgünleri bolan (Schema Registry/Artifact Registry) (BACKWARD/FORWARD/FULL).

Howpsuzlyk we laýyklyk

Şertnamanyň bir bölegi hökmünde tassyklamak/ygtyýarlandyrmak (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: gizlemek, tokenizasiýa formatlary, ýörite saklaýyş usullary bolan meýdanlar/TTL.
Audit syýasaty: hökmany atributlar ('actor', 'subject', 'action', 'occurred _ at', 'trace _ id').
Çäklendirmeler: rate limit headers, kwotalar, habarlaryň ölçegleri, möhletler.

Şertnama boýunça gözegçilik

Correlation/Request-ID: aýratynlykda hökmanydyr.
Error Catalog: kodlaryň we SLA-laryň düzedilen sanawy.
SLI/SLO: p50/p95 latency, üstünlikli jogaplaryň paýy, gabat gelýän wakalaryň paýy, idempotent gaýtalamalaryň paýy.

Synag we hili

Contract tests (sarp ediji üpjün ediji), CI-de schema diff, mok serwerlerini döretmek.
Golden samples: soraglaryň/jogaplaryň salgylanma mysallary, e2e üçin fiksturlar.
Chaos/latency injection: wagt/retraut barlagy, MGC saklananda giňelişleriň pese gaçmagy.

Mysal üçin domen şablonlary

Töleg (REST + wakalar)

'POST/payments' → '201 Created' s 'payment _ id', 'status = authorized'.
Waka 'payment. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
'Payment giňeltmek. enriched. v1 ': töwekgelçilik-skor, geo, device-fingerprint.
Ýalňyşlyklar: '422' (tassyklama), '402' (töleg required), '409' (duplicate).
SLA: ygtyýarnama ≤ 800ms p95; ýadro wakasy ≤ 2c lag p95.

KYC (gRPC + nobatlar)

RPC `StartVerification(user_id)` → `operation_id`.
'kyc' topikasyndaky ösüş wakalary. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Şertnama PII meýdanlaryny, saklanyş möhletini, maskalanmagyny, şowsuzlygyň sebäpler kodlaryny kesgitleýär.

Audit (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Baýlaşdyrmak: IP, device, geo - aýratyn waka/akym bilen, özeni petiklemeýär.

Gurallar we awtomatika (takmynan ys)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Geýtweý: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Reýestr: Shemalaryň git-katalogy + Schema Registry/Artifact Registry.
Resminamalar: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-pattern

Code-first by accident: "ilki bilen dolandyryjylarda MVP", faktumdan soňky aýratynlyklar, resminamalarda we hereketlerde gapma-garşylyklar.
Swagger-wash: Hakyky düzgünsiz resmi OpenAPI (ýalňyşlyklar, çäkler, SLA, wersiýalar).
Gabat gelýänligi ýok etmek: meýdan aýryldy/major wersiýasy bolmazdan görnüşi üýtgedildi; protobuf-tegleri gaýtadan ulanmak.
Paginasiýa/süzgüçsiz "galyň" jogap; idempotentligiň ýoklugy.
Şertnamadan daşary howpsuzlyk: auth/Scopes wiki hökmünde beýan edilýär, ýöne aýratynlykda däl.

Prosesiň guralyşy bilen özara gatnaşygy

API Guild: standartlaryň howandarlary, üýtgeşmeleriň gykylygy, okuw.
Design Docs: Her bir API üçin - PRD, ADR (çözgütler), SLA, töwekgelçilik matrisi.
Change Management: RFC-proses, release notes, migrasiýa gidleri, deprecation-time line.
Pawed Road & Templates: aýratynlyklardan hyzmat çarçuwalarynyň generatorlary (handler skeleti, tassyklama, logirleme).

Çek sahypalary

Başlamazdan öň

• PRD we domen sözlügi bar.
• Şemalaryň stili (REST/gRPC/Event/GraphQL) we formaty saýlandy.
• MGC, ýalňyşlyklar, SLA/SLO, idempotentlik düzgünleri kesgitlenildi.

Ösüşde

• Spesifikasiýa linterler we gözden geçirilýär.
• SDK/stab/fiksturyň awtogenerasiýasy sazlandy.
• Şertnama-synaglar (CDC) CI-e girizildi; schema-diff gabat gelmeýän üýtgeşmeleri bloklaýar.

Çykmazdan ozal

• Mysallar we ýalňyşlyk kodlary bolan integratorlar üçin resminamalar.
• Şertnama boýunça gözegçilik derejesi: correlation-id, error catalog, daşbordlar SLI.
• Wersiýa syýasaty we deprecation yglan edildi.

FAQ

Protocol-first API-first-den nähili tapawutlanýar?
Terminler köplenç sinonim hökmünde ulanylýar. Protocol-first atly bu makalada şertnamanyň berkligini we SLA, howpsuzlyk we gözegçilik ýaly ähli stilleriň (REST/RPC/Events/GraphQL) gurşawyny nygtaýarys.

Bu ösüşi haýallatarmy?
Başlangyç birneme uzyn bolup biler, ýöne soňra integrasiýalarda, durnuklylykda we paralel ösüş tizliginde (awtogenerasiýa, durnukly SDK) ýeňiş gazanýarys.

Çalt synaglar bilen näme etmeli?
Shemalaryň (draft), feature flags we sandyk gutusynyň "gara" wersiýalaryny ulanyň, ýöne linterleri we esasy laýyklyk düzgünlerini sypdyrmaň.

Jemi

Protocol-first dizaýny şertnamany arhitektura merkezi edýär: özüni alyp barşyny utgaşdyrýarys, shemalary düzýäris, nesil we synaglary awtomatlaşdyrýarys, goşmaça ösýäris. Netijede, öňünden aýdyp boljak integrasiýalary, ösüşiň ýokary tizligini we ulgamlaryň masştabyň we toparyň üýtgemegine garşylygyny alýarys.