Protocol-first дизайны

Protocol-first дегеніміз не?

Protocol-first - бұл компоненттер (сервистер, клиенттер, сыртқы әріптестер) арасындағы өзара іс-қимыл келісімшарты іске асырудан бұрын жобаланатын және тіркелетін тәсіл. Код, сақтау орындары, инфрақұрылым және құжаттама келісімшартқа бағынады және керісінше емес, одан автоматты түрде генерацияланады.

API тек кодтың жанама өнімі болып табылатын «code-first» дегеннен айырмашылығы, Protocol-first протоколды бастапқы артефактқа айналдырады: оған домен ұғымдары, деректер модельдері, мәртебелер, қателер, демпотенттік семантикасы, SLO/SLI және тіпті нұсқалар саясаты тиесілі.

Бұл не үшін қажет

Ұйым ауқымында интерфейстердің келісімділігі және болжамдылығы.
Жылдам онбординг (SDK/тұрақтардың/клиенттердің автогенерациясы, бірыңғай қателер мен кодтар).
Сенімді эволюция (схемалардың үйлесімділігі, келісім-тестілер, нұсқалардың нақты саясаты).
Өнімнің фокусы: кодты жазу алдында мінез-құлықты, SLA және UX интеграциясын талқылаймыз.
Автоматтандыру: CI/CD бір ақиқат көзінен артефактілерді (клиенттер, серверлік бұғаттағыштар, валидаторлар) жинайды.
Қауіпсіздік және комплаенс: құқықтар, PII бүркемелеу, ретенция саясаты келісімшартта бекітілген.

Өту өзегі

1. Бірыңғай ақиқат көзі (SSOT) - машинамен оқылатын ерекшеліктер:

REST: OpenAPI/JSON Schema.
Оқиғалар және стриминг: AsyncAPI, Euro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + директивалар/саясат.
2. Іске асыруға дейінгі уағдаластықтар: домен глоссарийі, қате кодтары, демпотенттік семантикасы, мерзім, ретра, дедупликация.
3. Автогенерация: клиенттер/серверлік штабтар, типтер, SDK, келісімшарттар-тесттер, моктар, Postman-коллекциялар, Terraform/OpenAPI Gateway- .
4. Governance: линтерлер/саясаттар (naming, pagination, сүзгілер, қателер), API гильдиясы арқылы review, мажорлық нұсқалар үшін change-advisory.
5. Сыйысымдылық: қатаң тексеру «additive-only», семантикалық нұсқалау, canary/consumer-driven тесттер.
6. Келісімшарт деңгейіндегі бақылау: корреляциялық ID, қателер модельдері, кідірістер бюджеттері хаттамада жазылған.

Процесс қандай (скелет)

1. Бастамасы: азық-түлік брифі → user journeys → API/Protocol PRD (ресурстар/әдістер/оқиғалар, SLA/SLO, қателер, лимиттер).
2. Модельдеу: спецификацияның жоба нұсқасы (OpenAPI/AsyncAPI/Proto) + деректер схемасы, терминдер сөздігі.
3. Шарттар және UX интеграция: пайдалы жүктеме мысалдары, қателер келісімшарттары, мәртебе карталары, нұсқалау ережелері.
4. Ревью және governance: линтерлер/стандарттар, домендік инварианттарды талқылау, lock-in MGC (ең аз кепілдік келісім-шарт).
5. Артефактілердің автогенерациясы: SDK, стаптар, тестілік фикстуралар, инфрақұрылым бітеуіштері (Gateways, IAM scopes).
6. Іске асыру және келісімшарт-тестілер: жеткізуші мен тұтынушылар CI-мен сәйкестігін тексеруден өтеді.
7. Бақылау және SLO: correlation-id, error catalog бойынша трассалау, ретрайлардың/таймауттардың бюджеттері.
8. Релиздер және эволюция: additive-first, deprecation policy, canary, A/B capability flags.

Өзара іс-қимыл хаттамалары мен стильдері

REST/HTTP

Стандарттар: ресурстық модель, 'GET/POST/PATCH/DELETE', пагинация (cursor), сүзгілер, сұрыптау.
Өрістер мен схемалар: JSON Schema, форматтар ('date-time', 'uuid'), инварианттар (regex/enum/min-max).
Қателер: бірыңғай пішім ('type', 'code', 'title', 'detail', 'trace _ id'), HTTP ағындарында маппинг.
Өзгерістерді бақылау: ETag/If-Match, POST үшін демпотенттік кілттер, 409/422 эксплициттік семантиктер.

gRPC/RPC

Protobuf: тегтердің тұрақты нөмірленуі, 'optional', қашықтағы өрістерді қайта пайдалануға тыйым салу.
Deadlines және келісімшарттағы басымдықтар; тұрақты мәртебелер (ОК, INVALID_ARGUMENT, FAILED_PRECONDITION, т.б.).
Streaming: хабарлар тәртібінің спецификациясы, backpressure, соңғы трейлерлер.

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

AsyncAPI: тақырыптар/арналар, партиялану кілттері, дедупликация, ретенция кілттері туралы келісімдер, семантика «тура бір рет» vs «кем дегенде бір рет».
Оқиға-ядро және байыту: ең аз payload және кеңейтуді бөлісу; 'event _ type '/' schema _ version' нұсқасын жасаңыз.
Ұқсастығы: 'event _ id', 'producer _ id', ретраялар және дедупликация бойынша policy.

GraphQL

SDL келісімшарт, депрекейтке арналған директивалар, тереңдік пен күрделілік лимиттері, қателер келісімшарты (error codes/extensions) ретінде.

Сәулет қағидаттарымен интеграциялау

Inverse Pyramid/Critical Path First: спецификациясында MGC (міндетті минимум), кеңейтулері - арқылы 'include = '/capabilities.
Paved Roads: дайын спецификация үлгілерінің жиынтығы (payment, KYC, audit, search, files) + линтерлер.
API Gateways & Service Mesh: келісімшарт негізіндегі саясат (rate-limits, auth scopes, retries, circuit-breakers).

Нұсқалау және эволюция

• Minor = тек аддитивті өрістер/арналар.
• Major = бұзатын өзгерістер (жою, қайта атау, семантиканы өзгерту).
• Deprecation Policy: қолдау терезелері, «Sunset» тақырыптары, хабарландыру оқиғалары.
• Consumer-Driven Contracts (CDC): Ағымдағы API нақты тұтынушыларды қанағаттандыратынын тексереміз.
• Схемалар каталогы: тарихы мен үйлесімділік ережелері бар тізілім (Schema Registry/Artifact Registry) (BACKWARD/FORWARD/FULL).

Қауіпсіздік және комплаенс

Аутентификация/авторизация келісімшарттың бір бөлігі ретінде (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: бүркемелеу, токендеу форматтары, ерекше сақтау режимі бар өрістер/TTL.
Аудит саясаты: міндетті төлсипаттар ('actor', 'subject', 'action', 'occurred _ at', 'trace _ id').
Лимиттер: rate limit headers, квоталар, хабарламалардың өлшемдері, мерзімдер.

Келісімшарт бойынша бақылау

Correlation/Request-ID: спецификацияда міндетті.
Error Catalog: кодтардың бекітілген тізімі және SLA жою.
SLI/SLO: p50/p95 latency, сәтті жауаптардың үлесі, үйлесімді оқиғалардың үлесі, іспеттес қайталаулардың үлесі.

Тестілеу және сапа

Contract tests (тұтынушы жеткізуші), CI-дегі schema diff, мок-серверлер генерациясы.
Golden samples: сұрау/жауаптардың эталондық мысалдары, e2e үшін фикстуралар.
Chaos/latency injection: таймауттарды/ретрайлерді тексеру, MGC сақталған кезде кеңейтулердің тозуы.

Үлгі домендік үлгілер

Төлем (REST + оқиға)

'POST/payments' (идемпотенттік кілт) → '201 Created' c 'payment _ id', 'status = authorized'.
'payment' оқиғасы. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
'payment. enriched. v1 ': тәуекел-скор, гео, device-fingerprint.
Қателер: '422' (валидация), '402' (payment required), '409' (duplicate).
SLA: авторизациялау ≤ 800ms p95; ядро оқиғасы ≤ 2с lag p95.

KYC (gRPC + кезек)

RPC `StartVerification(user_id)` → `operation_id`.
'kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Келісімшарт PII-өрістерді, сақтау мерзімін, жасыруды, бас тартудың себепті кодтарын көрсетеді.

Аудит (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Байыту: IP, device, geo - жеке оқиғамен/ағынмен, ядроны бөгемейді.

Құралдар және автоматика (үлгілік стек)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Гейтвей: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Тізілім: Git-каталог схемалары + Schema Registry/Artifact Registry.
Құжаттама: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Қарсы үлгілер

Code-first by accident: «алдымен контроллерлерде MVP», пост-фактум ерекшелігі, құжаттама мен мінез-құлық айырмашылығы.
Swagger-wash: нақты ережелері жоқ ресми OpenAPI (қателер, лимиттер, SLA, нұсқалар).
Үйлесімділіктің бұзылуы: өрісті жойды/major нұсқасыз түрін өзгертті; protobuf-тегтерді қайта пайдалану.
Пагинациясыз/сүзгісіз «қалың» жауап; іспеттіліктің болмауы.
Келісімшарттан тыс секьюритилер: auth/Scopes вики ретінде сипатталған, бірақ спецификацияда емес.

Процесті ұйымдастырумен өзара байланыс

API Guild: стандарттардың қамқоршылары, өзгерістер, оқыту.
Design Docs: әрбір API үшін - PRD, ADR (шешімдер), SLA, тәуекелдер матрицасы.
Change Management: RFC-процесс, release notes, миграциялық гайдтар, deprecation-таймлайн.
Paved Road & Templates: спецификациядан сервис қаңқаларының генераторлары (хендлер скелеті, валидация, логизация).

Чек парақтары

Бастау алдында

• Доменнің PRD және глоссарий бар.
• Сұлба мәнері (REST/gRPC/Event/GraphQL) және пішімі таңдалды.
• Анықталған MGC, қателер, SLA/SLO, теңсіздік ережелері.

Әзірлеуде

• Спецификация линтерлер мен review өтеді.
• SDK/тұрақтардың/фикстураның автогенерациясы теңшелген.
• Келісімшарт-тесттер (CDC) CI-ге енгізілген; schema-diff сыйыспайтын өзгерістерді бұғаттайды.

Шығару алдында

• Мысалдары мен қате кодтары бар интеграторларға арналған құжаттама.
• Келісімшарт бойынша бақылау: correlation-id, error catalog, SLI дашбордтар.
• Нұсқалық және deprecation саясаты жарияланды.

FAQ

Protocol-first API-first-тен қалай ерекшеленеді?
Терминдер жиі синоним ретінде пайдаланылады. Бұл мақалада Protocol-first деп біз келісімшарттың қатаңдығын және SLA, қауіпсіздік және байқауды қоса алғанда, барлық стильдерді (REST/RPC/Events/GraphQL) қамтуды атап өтеміз.

Бұл дамуды баяулатпайды ма?
Бастау сәл ұзағырақ болуы мүмкін, бірақ содан кейін интеграцияларда, тұрақтылықта және параллельді игеру жылдамдығында (автогенерация, тұрақты SDK) ұтып аламыз.

Жылдам эксперименттермен не істеу керек?
Схемалардың (draft), feature flags және құмсалғыштардың «бастапқы» нұсқаларын пайдаланыңыз, бірақ линтерлер мен негізгі сыйысымдылық ережелерін жіберіп алмаңыз.

Жиынтығы

Protocol-first дизайны келісімшартты архитектураның орталығына айналдырады: мінез-құлықты үйлестіреді, схемаларды бекітеді, генерация мен тесттерді автоматтандырады, аддитивті түрде дамиды. Нәтижесінде болжамды интеграциялар, дамудың жоғары жылдамдығы және жүйелердің ауқым мен команданың өзгеруіне тұрақтылығы алынады.