Протокол-тарҳи аввал

Протокол-аввал чист

Протокол-аввал равишест, ки дар он шартномаи ҳамкорӣ байни ҷузъҳо (хидматҳо, муштариён, шарикони беруна) пеш аз татбиқ таҳия ва муқаррар карда мешавад. Кодекс, нигаҳдорӣ, инфрасохтор ва ҳуҷҷатгузорӣ тибқи шартнома баста мешаванд ва ба таври худкор аз он тавлид мешаванд, на баръакс.

Баръакси рамзи аввал, ки дар он API танҳо маҳсулоти иловагии код аст, Протокол-аввал протоколро артефакти аввалия месозад: он дорои мафҳумҳои домейн, моделҳои маълумот, статусҳо, хатогиҳо, семантикаи idempotency, SLO/SLI ва ҳатто сиёсати версия мебошад.

Чаро ба шумо лозим аст?

Мувофиқат ва пешгӯии интерфейсҳо дар тамоми созмон.
Боркунии зуд (SDK/автогенератсияи устувор/муштарӣ, хатогиҳо ва рамзҳои ягона).
Таҳаввулоти боэътимод (мутобиқати схемаҳо, шартномаҳои санҷишӣ, сиёсати возеҳи версия).
Фокуси маҳсулот: Пеш аз навиштани код, рафтори SLA ва UX-ро муҳокима кунед.
Автоматика: CI/CD артефактҳо (мизоҷон, стубҳои сервер, валидаторҳо) -ро аз як манбаи ягонаи ҳақиқат ҷамъоварӣ мекунад.
Амният ва риояи он: ҳуқуқҳо, ниқоби PII, сиёсати нигоҳдорӣ дар шартнома тасдиқ карда шудаанд.

Усули асосӣ

1. Манбаи ягонаи ҳақиқат (SSOT) - мушаххасоти хонданашаванда:

Истироҳат: Схемаи Open/API/JSON.
Чорабиниҳо ва ҷараёнҳо: Async-API, Avro/JSON Schema.
RPC: Protobuf (GRPC), Thrift, Smithy.
Диаграммаи QL: SDL + дастурҳо/сиёсатҳо.
2. Тартиби пеш аз татбиқ: луғати домейн, рамзҳои хатогӣ, семантикаи номутаносибӣ, мӯҳлатҳо, бознишастагӣ, такрорӣ.
3. Автогенератсия: мизоҷон/стубҳои сервер, намудҳо, SDK, шартномаҳои санҷишӣ, moks, коллексияҳои Postman, Terraform/API Gateway конфигуратсия.
4. Идоракунӣ: линтерҳо/сиёсатҳо (номгузорӣ, саҳифабандӣ, филтрҳо, хатогиҳо), бознигарӣ тавассути гильдияи API, машварати тағирот барои версияҳои асосӣ.
5. Мутобиқат: санҷиши қатъии диффузияҳои "танҳо-иловагӣ", версияи семантикӣ, санҷишҳои канарӣ/истеъмолӣ.
6. Мушоҳида дар сатҳи шартнома: шаҳодатномаҳои коррелятсионӣ, моделҳои хатогӣ, буҷаҳои таъхир дар протокол навишта шудаанд.

Раванд чӣ гуна ба назар мерасад (скелет)

1. Ташаббус: мухтасар дар бораи сафарҳои истифодабаранда → API/Protocol PRD (захираҳо/усулҳо/рӯйдодҳо, SLA/SLO, хатогиҳо, маҳдудиятҳо).

2. Моделсозӣ: лоиҳаи мушаххасот (Open

3. Шартномаҳо ва ҳамгироии UX: намунаҳои сарборӣ, шартномаҳои хатогӣ, харитаҳои вазъ, қоидаҳои версия.
4. Баррасӣ ва идоракунӣ: линтерҳо/стандартҳо, муҳокимаи инвариантҳои домейн, қулф кардани MGC (шартномаи ҳадди аққали кафолат).
5. Истеҳсоли худкори артефактҳо: SDK, корд, ислоҳи санҷишҳо, пойгоҳҳои инфрасохторӣ (дарвозаҳо, миқёси IAM).
6. Санҷишҳои амалисозӣ ва шартномавӣ: Таъминкунанда ва истеъмолкунандагон дар CI аз санҷиши мутобиқат мегузаранд.
7. Мушоҳида ва SLO: пайгирии таносуби идентификатсия, каталоги хатогӣ, буҷаи бозгашт/таъхири вақт.
8. Релизҳо ва таҳаввулот: иловаи аввал, сиёсати радкунӣ, канарейка, парчамҳои қобилияти A/B.

Протоколҳо ва услубҳои муштарак

REST/HTTP

Стандартҳо: модели захираҳо, 'GET/POST/PATCH/DELETE', пагинатсия (курсор), филтрҳо, навъбандӣ.
Майдонҳо ва схемаҳо: JSON Schema, форматҳо ('санаи вақт', 'uuid'), инвариантҳо (regex/enum/min-max).
Хатогиҳо: формати ягона ('намуд', 'рамз', 'унвон', 'тафсилот', 'trace _ id'), харитасозӣ ба стекҳои HTTP.
Назорати тағирот: ET .ag/If-Match, калидҳои idempotent барои POST, семантикаи возеҳ 409/422.

GRPC/RPC

Protobuf: рақамгузории теги устувор, 'ихтиёрӣ', истифодаи такрории майдонҳои ҳазфшударо манъ мекунад.
Мӯҳлатҳо ва афзалиятҳои шартнома; статусҳои устувор (OK, INVALID_ARGUMENT, FAILED_PRECONDITION ва ғайра).
Ҷараён: мушаххасоти фармоиши паём, backpressure, трейлерҳои ниҳоӣ.

Рӯйдодҳо (Кафка/NATS/SNS/SQS)

Async-API: мавзӯъҳо/каналҳо, калидҳои тақсимкунӣ, конвенсияҳои калидӣ, нигоҳдорӣ, семантикаи як маротиба "против" ҳадди аққал як бор "

Ҳодисаи асосӣ ва ғанисозӣ: сарборӣ ва васеъкунии ҳадди ақали алоҳида; версияи 'event _ type '/' schema _ version'.
Idempotency: 'event _ id', 'productor _ id', сиёсат оид ба бознигарӣ ва такрорӣ.

Диаграммаи QL

SDL ҳамчун шартнома, дастурҳо барои фарсудашавӣ, маҳдудиятҳои амиқ ва мураккаб, рамзҳои хатогӣ/тамдиди шартнома.

Ҳамгироӣ бо принсипҳои меъморӣ

Роҳи баръакси пирамида/роҳи интиқодӣ Аввал: дар мушаххасот, MGC (ҳадди аққали ҳатмӣ), васеъшавиро тавассути '? дохил = '/қобилиятҳо.
Роҳҳои мумфарш: маҷмӯи қолабҳои мушаххаси тайёр (пардохт, KYC, аудит, ҷустуҷӯ, файлҳо) + линтерҳо.
API Gateways & Service Mesh: сиёсати шартномавӣ (маҳдудиятҳо, миқёси auth, retries, схемаҳо).

Версия ва эволютсия

• Минор = танҳо майдонҳо/каналҳои иловагӣ.
• Major = шикастани тағирот (несткунӣ, номгузорӣ, тағир додани семантика).
• Сиёсати радкунӣ: дастгирии тирезаҳо, сарлавҳаҳои 'Ғуруби офтоб', рӯйдодҳои огоҳӣ.
• Шартномаҳои истеъмолкунанда (CDC): Тасдиқи он, ки API-и кунунӣ истеъмолкунандагони мушаххасро қонеъ мекунад.
• Феҳристи схема: Феҳристи схема/Феҳристи артифакт бо қоидаҳои таърих ва мутобиқат (BACKWARD/FORWARD/FULL).

Бехатарӣ ва риояи

Аутентификатсия/авторизатсия ҳамчун як қисми шартнома (OAuth2/OIDC миқёс, mTLS, даъвоҳои JWT).
PII/PCI: ниқоб, форматҳои токенизатсия, майдонҳо бо режими махсуси нигоҳдорӣ/TTL.
Сиёсатҳои аудит: атрибутҳои зарурӣ ('актёр', 'мавзӯъ', 'амал', 'рух дод _ at', 'trace _ id').
Маҳдудиятҳо: меъёри сарлавҳаҳо, квотаҳо, андозаи паёмҳо, мӯҳлатҳо.

Риояи шартнома

Таносуб/Дархост-ID: дар мушаххасот талаб карда мешавад.
Каталоги хатогӣ - рӯйхати собитшудаи рамзҳо ва SLA-ҳо барои ҳал кардан.
SLI/SLO: таъхири p50/p95, таносуби посухҳои муваффақ, таносуби рӯйдодҳои мувофиқ, таносуби такрори idempotent.

Озмоиш ва сифат

Санҷишҳои шартномавӣ (провайдер ↔ истеъмолкунанда), схема дар CI, насли серверҳои масхара.
Намунаҳои тиллоӣ: намунаҳои истинодҳои дархостҳо/посухҳо, асбобҳо барои e2e.
Тазриқи бесарусомонӣ/дермонӣ: санҷиши вақт/бозсозӣ, таназзули васеъшавӣ ҳангоми сарфаи MGC.

Қолибҳои намунавии домейн

Пардохт (REST + Чорабиниҳо)

'POST/пардохтҳо' → '201 сохта шудааст' бо 'pay _ id', 'status = ваколатдор'.
Пардохти чорабинӣ. ваколатдор шудааст. v1 '(yydro):' {payment_id, маблағ, асъор, усул, occurred_at} '.
Тамдиди 'пардохт. ғанӣ гардонида шудааст. v1 ': меъёри хатар, гео, изи ангуштони дастгоҳ.
Хатогиҳо: '422' (тасдиқ), '402' (пардохт талаб карда мешавад), '409' (нусхабардорӣ).
SLA: иҷозат ≤ 800ms p95; ҳодисаи ядро ≤ 2c ақибмонӣ p95.

KYC (навбатҳои gRPC +)

RPC 'Оғози санҷиш (user_id)' → 'operation _ id'.
Рӯйдодҳои пешрафт дар мавзӯи 'kyc. статус. v1 '(' Интизорӣ '→' ТАСДИҚ/РАД ').
Дар шартнома майдонҳои PII, мӯҳлати нигоҳдорӣ, ниқоб, рамзҳои нокомии сабабҳо пешбинӣ шудаанд.

Аудит (Танҳо ҳодиса)

'аудит. сабт шудааст. v1 '(yydro):' актёр ',' мавзӯъ ',' амал ',' рух дод _ at ',' trace _ id '.
Ғанисозӣ: IP, дастгоҳ, гео - ҳодиса/риштаи алоҳида, ядро ​ ​ баста намешавад.

Асбобҳо ва автоматизатсия (стеки тахминӣ)

Спеки: Open

Линтеры: Санҷишҳои мутобиқати пайвастшавӣ бо SR.

Генерация: Генератори Open

Дарвоза: Kong/Apigee/Azure/GCP GW, намоянда.

Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, Mock

Сабти ном: Git-феҳристи схемаҳо + Феҳристи схема/Феҳристи артифактҳо.
Ҳуҷҷатгузорӣ: Redocly/Stoplight/Swagger-UI/Graphi-QL/Explorer.

Анти-намунаҳо

Кодекс-аввал тасодуфан: "MVP аввал дар контроллерҳо", мушаххасоти пас аз воқеӣ, фарқияти байни ҳуҷҷатгузорӣ ва рафтор.
Swagger-шустан: Open-API-и расмӣ бидуни қоидаҳои воқеӣ (хатогиҳо, маҳдудиятҳо, SLA, версияҳо).
Танаффуси мутобиқат: майдони хориҷшуда/навъи ивазшуда бидуни версияи асосӣ; истифодаи такрории барчаспҳои протобуф.
Ҷавоби "ғафс" бидуни пагинатсия/филтрҳо; набудани idempotency.
Амнияти берун аз шартнома: auth/Scopes дар вики тасвир карда шудаанд, аммо на дар мушаххасот.

Робита барои коркарди созмон

Гильдияи API: сарпарастони стандартҳо, бознигарӣ, омӯзиш.
Ҳуҷҷатҳои тарроҳӣ: барои ҳар як API - PRD, ADR (қарорҳо), SLA, матритсаи хатар.
Идоракунии тағирот: Раванди RFC, қайдҳои нашр, дастурҳои муҳоҷират, ҷадвали дуршавӣ.
Роҳ ва қолибҳои мумфарш: генераторҳои чаҳорчӯбаи хидматрасонӣ аз мушаххасот (скелети дастӣ, санҷиш, воридшавӣ).

Рӯйхати назоратӣ

Пеш аз оғоз

• PRD ва луғати домейн мавҷуд аст.
• Услуби интихобшуда (формати REST/GRPC/Event/GraphQL) ва формати схема.
• MGC-ҳо, хатогиҳо, SLA/SLO-ҳо, қоидаҳои idempotency муайян карда шудаанд.

Дар марҳилаи таҳия

• Мушаххасот линтерҳо ва баррасиро мегузарад.
• Тавлиди худкори SDK/Stable/Fixture танзим карда мешавад.
• Санҷишҳои шартномавӣ (CDC) ба CI дохил карда мешаванд; схема-дифф тағироти номувофиқро блок мекунад.

Пеш аз нашр

• Ҳуҷҷатҳои интегратор бо намунаҳо ва рамзҳои хатогӣ.
• Шартномавӣ мушоҳида карда мешавад: коррелятсия-id, каталоги хатогӣ, панелҳои SLI.
• Сиёсати амортизатсия ва амортизатсия эълон карда мешавад.

FAQ

Протокол-аввал аз API-аввал чӣ фарқ дорад?
Аксар вақт истилоҳҳо бо ҳам иваз мешаванд. Дар ин мақола тибқи Протокол-аввал, мо қатъии шартнома ва фарогирии ҳама услубҳоро (REST/RPC/Events/GraphQL), аз ҷумла SLA, бехатарӣ ва мушоҳидаҳоро таъкид мекунем.

Оё ин рушдро суст мекунад?
Оғоз метавонад каме дарозтар бошад, аммо пас мо дар ҳамгироӣ, устуворӣ ва суръати рушди мувозӣ ғолиб мешавем (тавлиди худкор, SDK-ҳои устувор).

Бо таҷрибаҳои зуд чӣ бояд кард?
Версияҳои "лоиҳавӣ" -и схемаҳо (лоиҳаҳо), парчамҳо ва қуттиҳои қуттиҳоро истифода баред, аммо линтерҳо ва қоидаҳои асосии мутобиқатро аз даст надиҳед.

Ҷамъ

Тарҳи протокол-аввал шартномаро маркази меъморӣ месозад: мо рафторро ҳамоҳанг месозем, схемаҳоро ислоҳ мекунем, тавлид ва санҷишҳоро автоматӣ мекунем, иловатан таҳаввул мекунем. Дар натиҷа, мо интегратсияҳои пешгӯишаванда, суръати баланди рушд ва муқовимати системаҳоро ба тағирот дар миқёс ва фармон мегирем.