Protocol-first дизайн

Що таке Protocol-first

Protocol-first - це підхід, в якому контракт взаємодії між компонентами (сервісами, клієнтами, зовнішніми партнерами) проектується і фіксується раніше реалізації. Код, сховища, інфраструктура і документація підкоряються контракту і автоматично з нього генеруються, а не навпаки.

На відміну від «code-first», де API - лише побічний продукт коду, Protocol-first робить протокол первинним артефактом: йому належать поняття домену, моделі даних, статуси, помилки, семантика ідемпотентності, SLO/SLI і навіть політика версій.

Навіщо це потрібно

Узгодженість і передбачуваність інтерфейсів в масштабах організації.
Швидкий онбординг (автогенерація SDK/стабів/клієнтів, єдині помилки і коди).
Надійна еволюція (сумісність схем, контракти-тести, чітка політика версій).
Продуктовий фокус: обговорюємо поведінку, SLA і UX інтеграції до написання коду.
Автоматизація: CI/CD збирає артефакти (клієнти, серверні заглушки, валідатори) з одного джерела істини.
Безпека та комплаєнс: права, маскування PII, політики ретенції закріплені в контракті.

Ядро підходу

1. Єдине джерело істини (SSOT) - машинно-читані специфікації:

REST: OpenAPI/JSON Schema.
Події та стрімінг: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + директиви/політики.
2. Домовленості до реалізації: глосарій домену, коди помилок, семантика ідемпотентності, дедлайни, ретраї, дедуплікація.
3. Автогенерація: клієнти/серверні стаби, типи, SDK, контракти-тести, моки, Postman-колекції, Terraform/OpenAPI Gateway-конфіг.
4. Governance: лінтери/політики (naming, пагінація, фільтри, помилки), review через API-гільдію, 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 і пріоритети в контракті; стабільні статуси (OK, INVALID_ARGUMENT, FAILED_PRECONDITION, etc.).
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 (постачальник ↔ споживач), schema diff в CI, генерація мок-серверів.
Golden samples: еталонні приклади запитів/відповідей, фікстури для e2e.
Chaos/latency injection: перевірка таймаутів/ретраїв, деградація розширень при збереженні MGC.

Зразкові доменні шаблони

Платіж (REST + події)

'POST/payments'( ідемпотентний ключ) →'201 Created'з'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: авторизація ≤ 800мс 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 ми підкреслюємо строгість контракту і охоплення всіх стилів (REST/RPC/Events/GraphQL), включаючи SLA, безпеку і спостережуваність.

Чи не уповільнить це розробку?
Старт може бути трохи довше, але потім виграємо на інтеграціях, стабільності і швидкостях паралельної розробки (автогенерація, стабільні SDK).

Що робити з швидкими експериментами?
Використовуйте «чорнові» версії схем (draft), feature flags і пісочниці, але не пропускайте лінтери і базові правила сумісності.

Підсумок

Protocol-first дизайн робить контракт центром архітектури: узгоджуємо поведінку, фіксуємо схеми, автоматизуємо генерацію і тести, еволюціонуємо адитивно. В результаті отримуємо передбачувані інтеграції, високу швидкість розвитку і стійкість систем до змін масштабу і команди.