Protocol-биринчи дизайн

Protocol-first деген эмне

Protocol-first - бул компоненттердин (сервистердин, кардарлардын, тышкы өнөктөштөрдүн) ортосундагы өз ара аракеттенүү келишими ишке ашыруудан мурда долбоорлонгон жана белгиленген ыкма. Код, кампалар, инфраструктура жана документтер контрактка баш ийет жана андан автоматтык түрдө түзүлөт, тескерисинче эмес.

"code-first" айырмаланып, анда API - коддун бир гана кошумча продукт, Protocol-first протоколду баштапкы артефакт кылат: домен түшүнүктөрү, маалыматтар моделдери, статустар, каталар, семантика, SLO/SLI жана ал тургай, версия саясаты таандык.

Эмне үчүн керек

Уюштуруунун масштабында интерфейстердин шайкештиги жана алдын ала айтылышы.
Fast Conbording (SDK/туруктуулук/кардарлар, бирдиктүү каталар жана коддору).
Ишенимдүү эволюция (схемалардын шайкештиги, контракттар-тесттер, так версиялар саясаты).
Продукт фокусу: кодду жазганга чейин жүрүм-турумун, SLA жана UX интеграциясын талкуулайбыз.
Automation: CI/CD чындыктын бир булагынан артефакттарды (кардарлар, сервердик штепсельдер, валидаторлор) чогултат.
Коопсуздук жана комплаенс: укуктар, PII жашыруу, ретенция саясаты келишимде бекитилген.

Мамиле өзөгү

1. Бир чындык булагы (SSOT) - машинада окуу өзгөчөлүктөрү:

REST: OpenAPI/JSON Schema.
Окуялар жана агымы: AsyncAPI, Euro/JSON схемасы.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + көрсөтмөлөр/саясат.
2. Ишке ашырууга чейинки макулдашуулар: домен глоссарийи, ката коддору, демпотенттик семантикасы, мөөнөтү, ретраи, дедупликация.
3. Autogeneration: кардарлар/Server кампалары, түрлөрү, SDK, келишимдер-тесттер, моктор, Postman-Collection, Terraform/OpenAPI Gateway- .
4. Governance: linters/саясат (naming, pagination, чыпкалар, каталар), API Guild аркылуу review, негизги нускалары үчүн өзгөрүү-advisory.
5. шайкештиги: катуу текшерүү "additive-only", семантикалык чыгаруу, canary/керектөөчү-айдоо тесттер.
6. Келишим деңгээлиндеги байкоо: корреляциялык ID, ката моделдери, кечигүү бюджеттери протоколдо жазылган.

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

1. Демилге: азык-түлүк бриф → колдонуучу journeys → API/Protocol PRD (ресурстар/ыкмалар/окуялар, SLA/SLO, каталар, лимиттер).
2. моделдөө: чийме өзгөчөлүктөрү (OpenAPI/AsyncAPI/Proto) + маалымат схемалары, терминдер сөздүгү.
3. Келишимдер жана UX интеграциясы: пайдалуу жүктүн мисалдары, ката келишимдери, статус карталары, версиялоо эрежелери.
4. Review жана governance: linters/стандарттар, домендик инварианттарды талкуулоо, MGC кулпусу (минималдуу кепилдик келишими).
5. Артефакттардын автогенерациясы: SDK, лагерлер, тесттик фикстуралар, инфраструктуралык капкактар (Gateways, IAM scopes).
6. Ишке ашыруу жана контракт-тесттер: жеткирүүчү жана керектөөчүлөр CI шайкештикти текшерүүдөн өтүшөт.
7. Байкоо жана SLO: correlation-id, error catalog, retrains/таймауттар бюджеттери боюнча жол.
8. Чыгарылыштар жана эволюция: additive-first, deprecation policy, canary, A/B capability flags.

Протоколдор жана өз ара стили

REST/HTTP

Стандарттар: ресурстук модели, 'GET/POST/PATCH/DELETE', пагинация (cursor), чыпкалар, сорттоо.
Талаалар жана схемалар: JSON схемасы, форматтар ('date-time', 'uid'), инварианттар (regex/enum/min-max).
Каталар: бирдиктүү формат ('type', 'code', 'title', 'detail', 'trace _ id'), HTTP жонундо mapping.
Өзгөрүүлөрдү көзөмөлдөө: ETag/If-Match, POST үчүн демпотент ачкычтары, 409/422 эксплицит семантикасы.

gRPC/RPC

Protobuf: туруктуу тег саны, 'optional', алыскы талааларды кайра колдонууга тыюу салуу.
Deadlines жана келишимде артыкчылыктар; туруктуу статустар (OK, INVALID_ARGUMENT, FAILED_PRECONDITION, ж.б.).
Streaming: билдирүү тартиби, backpressure, акыркы трейлер.

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

AsyncAPI: темалар/каналдар, партиялаштыруу ачкычтары, дедупликация ачкычтары, ретенция, семантика "так бир жолу" vs "жок дегенде бир жолу".
Негизги иш-чара жана байытуу: минималдуу төлөм жана кеңейтүү бөлүшүү; 'event _ type '/' schema _ version' версиясын түзүңүз.
Демпотенттик: 'event _ id', 'producer _ id', ретра жана дедупликация боюнча саясат.

GraphQL

SDL келишим катары, депрекейт үчүн көрсөтмөлөр, тереңдиктин жана кыйынчылыктардын чектери, ката келишими (error codes/extensions).

Архитектура принциптери менен интеграция

Inverse Pyramid/Critical Path First: спецификациясында MGC (милдеттүү минимум), кеңейтүү - аркылуу? include = '/capabilities.
Paved Жолдор: даяр мүнөздөмө үлгүлөрүнүн топтому (төлөм, KYC, аудит, издөө, 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деги схемасы diff, мок серверлеринин генерациясы.
Алтын үлгүлөрү: суроо-талаптардын/жооптордун үлгүлөрү, e2e үчүн фикстуралар.
Chaos/latency injection: MGC сактоо менен убакыт/retraut текшерүү, кеңейтүүлөрдүн бузулушу.

Болжолдуу домен үлгүлөрү

Төлөм (REST + окуялар)

'POST/payments' (демпотенттик ачкыч) → '201 Created' s '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, гео - өзүнчө иш-чара/агым, негизги бөгөттөп жок.

Инструменттер жана автоматика (болжол менен стек)

Спеки: 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.
Реестр: Git-каталог схемалар + Schema Registry/Artifact Registry.
Документация: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Анти-үлгүлөрү

Code-first by accident: "Контроллерлерде биринчи MVP", пост-факт спецификациясы, документтердин жана жүрүм-турумдун келишпестиги.
Swagger-wash: расмий OpenAPI эч кандай чыныгы эрежелер (каталар, чектер, SLA, нускалары).
Шайкештиктин бузулушу: негизги версиясы жок талааны алып салуу/түрүн өзгөртүү; protobuf тегтерин кайра колдонуу.
пагинация/чыпкалар жок "жоон" жооп; демпотенттиктин жоктугу.
Келишимден тышкары Security: auth/Scopes wiki сүрөттөлгөн, бирок спецификациясында эмес.

Процессти уюштуруу менен байланыш

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

Чек баракчалары

Башталганга чейин

• домен PRD жана глоссарий бар.
• Тандалган стили (REST/gRPC/Event/GraphQL) жана схемалар формат.
• Аныкталган MGC, каталар, SLA/SLO, жол эрежелери.

Иштеп чыгуу

• Specification linters жана review өтөт.
• SDK Auto Generation/Stabils/Fixture орнотулган.
• Келишим-тесттер (CDC) CI киргизилген; schema-diff шайкеш келбеген өзгөрүүлөргө бөгөт коёт.

Чыгаруу алдында

• мисалдар жана ката коддору менен интеграторлор үчүн документтер.
• Келишим боюнча байкоо: correlation-id, error catalog, dashbord SLI.
• Версия саясаты жана deprecation жарыяланган.

FAQ

Protocol-first API-first айырмаланат?
Терминдер көбүнчө синоним катары колдонулат. Бул макалада Protocol-биринчи биз келишимдин катаалдыгын жана бардык стилдерди (REST/RPC/Events/GraphQL), анын ичинде SLA, коопсуздук жана байкоо камтууну баса белгилешет.

Бул өнүгүүнү жайлатпайбы?
Баштоо бир аз узакка созулушу мүмкүн, бирок андан кийин интеграцияларды, туруктуулукту жана параллелдүү өнүгүүнүн ылдамдыгын (автогенерация, туруктуу SDK) утуп алабыз.

тез эксперименттер менен эмне кылуу керек?
схемалар (draft), feature flags жана Sandbox, бирок линтерлер жана негизги шайкештик эрежелерин сагынам эмес, "чийме" нускасын колдонуу.

Жыйынтык

Protocol-биринчи дизайн архитектуранын келишим борборун түзөт: жүрүм-турумун координациялоо, схемаларды бекитүү, генерацияны жана тесттерди автоматташтыруу, кошумча эволюция. Натыйжада биз алдын ала интеграцияны, жогорку өнүгүү ылдамдыгын жана системалардын масштабдагы жана командадагы өзгөрүүлөргө туруктуулугун алабыз.