Тікелей сыйысымдылық

Тікелей үйлесімділік дегеніміз не?

Тікелей үйлесімділік (forward compatibility) - бұл жүйенің ол бастапқыда жобаланғанға қарағанда неғұрлым жаңа клиенттермен немесе деректермен дұрыс жұмыс істеу қабілеті. Қарапайым: ескі сервер оған жаңа клиент келгенде бұзылмайды; ескі тұтынушы жаңа хабарды кездескенде құлдырамайды.

Кері үйлесімділіктен (жаңа жүйе ескі клиенттерді қолдайтын кезде) forward жауапкершілік бағытымен ерекшеленеді: біз хаттамаларды және клиенттерді болашақ кеңейтулерді бүкіл экожүйені жаппай жаңартусыз «аман қалу» үшін жобалаймыз.

Базалық қағидаттар

1. Tolerant reader & tolerant writer

Reader белгісіз өрістерді/тақырыптарды елемейді және дұрыс fallback бар жаңа enum мәндеріне рұқсат береді.
Writer сервері қолдау көрсетілетін ретінде жарияламаған ештеңе жібермейді (capabilities).

2. Capability negotiation

handshake-сатысында айқын мүмкіндіктер алмасу (фич/нұсқалар/медиа-типтер). Клиент өзінің мінез-құлқын сервердің жауабына бейімдейді.

3. Дефолттық тозу

Жаңа мүмкіндіктер опциондық болып саналады: егер сервер/консюмер оларды қолдамаса, сценарий бәрібір пайдалы минимуммен (MGC) аяқталады.

4. Тұрақты ядро (MGC)

Ең төменгі кепілдік келісімшарт өзгермейді; жаңалықтар кеңею ретінде өмір сүреді.

5. Қате келісімшарттары хаттаманың бір бөлігі ретінде

Болжамды кодтар/себептер («фича қолдау көрсетілмейді», «медиа түрі белгісіз») клиентке қолдау көрсетілетін режимге автоматты түрде қайтуға мүмкіндік береді.

6. Күтпеген нұсқалар

Мажорлық сызықтар бөлінген; кішігірім кеңейтулер серверді/консумерді жаңартуды қажет етпейді.

Бұл ерекше маңызды жерде

Ұзақ мерзімді интеграциялары бар жария API (серіктестер, мобильді қосымшалардағы SDK).
Көптеген тәуелсіз консумерлері бар оқиғалық платформалар.
Бэкендке қарағанда баяу жаңартылатын мобильді клиенттер.
Эдж/IoT, мұнда құрылғылар паркінің бір бөлігі сирек тігіледі.

Мәнерлер бойынша сату үлгілері

REST/HTTP

Negotiation:

'Accept '/параметрлері бар медиатиптер (' application/vnd. example. order+json; v=1; profile=risk`).
'Prefer: include =...' опциондық блоктар үшін.
Тақырыбы 'X-Capabilities: risk_score,item_details_v2'.

Клиенттің мінез-құлқы:

Негізгі пішімде сұрау жібереді, кеңейтулер - сервер capability растаған жағдайда ғана (OPTIONS/desc/лид-эндпоинт арқылы).
'415/406/501' қолданатын пішімге/әдіске автоматты түрде домалатылады.
Сервердің жауабы: белгісіз параметрлер - елемеу; артық өрістер - рұқсат етіледі; қате пішімі тұрақты ('type/code/detail/trace _ id').

gRPC / Protobuf

Тұрақты сервистер: жаңа әдістер/өрістер - аддитивті; ескі сервер сұраудың белгісіз өрістерін тыныш елемейді.
Feature discovery: 'GetCapabilities ()' әдісі фич/лимит тізімдерін қайтарады. Егер сервер оны жарияламаса, клиент «v2-әдісін» шақырмайды.
Стриминг: хабарламаларды ең аз теру тәртібін белгілеңіз; Жаңа «жақтауларды» ескі клиент елемейтін кеңейтімдермен/түрлермен белгілеңіз.

GraphQL

Forward-friendly: жаңа өрістер/түрлер серверде пайда болады - ескі клиенттер оларды сұратпайды.
Болжамдарға тыйым салынады: клиент схеманы (интроспекция/кодоген) ұстауы және белгісіз директиваларды/айнымалыларды жібермеуі тиіс.
Деградация: егер сервер кастомдық директиваны/feature білмесе, клиент онсыз сұрауды жасайды.

Event-driven (Kafka/NATS/Pulsar, Avro/JSON/Proto)

Тізімдегі схеманың FORWARD сыйысымдылығы: ескі консумерлер жаңа схемамен жазылған хабарларды оқи алады.
Дефолты бар аддитивті өрістер: жаңа продюсерлер ескі консьюмерлерді сындырмайды.
Core vs Enriched: ядро бұрынғы күйінде қалады, жаңа мәліметтер '.enriched' -те немесе қосымша өрістер ретінде жарияланады.

Жобалау тәжірибесі

1. Ең аз сұрау салу шарты (MGC)

Әрекеттің «тар мойыны» болуы керек, оны барлық серверлер көп жылдар бойы қолдайды.

2. Келісімшарт деңгейіндегі фича-жалаулар

Фичтерді аталған мүмкіндіктер ретінде сипаттаңыз: 'risk _ score', 'pricing _ v2', 'strong _ idempotency'. Клиент оларды анық қамтиды.

3. «қолданбайды» үшін анық қате кодтары

HTTP: `501 Not Implemented`, `415 Unsupported Media Type`, детальные `problem+json`.
gRPC: `UNIMPLEMENTED`/`FAILED_PRECONDITION`.
Events: DLQ бағыты с 'reason = unsupported _ feature'.

4. Реті/толық тізімдеріне сүйенбеу

Клиент жаңа enum мәндеріне, жаңа өрістердің болмауына және «қосымша» сипаттарға дайын болуы тиіс.

5. Тұрақты идентификаторлар мен пішімдер

Сызық ішінде ID/партиялану кілттерінің пішімін өзгертпеңіз - бұл оқырмандар жағындағы forward-ды бұзады.

6. Машинамен оқылатын құжаттама

OpenAPI/AsyncAPI/Proto descriptors/GraphQL SDL. Клиенттер фич қолдауын салыстыра алады.

Forward-үйлесімділігін тестілеу

FORWARD/FULL режиміндегі Schema-diff: жаңа схема ескі тұтынушыны/серверді валидациялайды.
Клиенттің келісімшарттық тесттері: жаңа клиент ескі серверге қарсы орындалады.
Golden requests: «жаңа» сұраулар жиыны «ескі» сервер арқылы жылжытылады; сыни қателерсіз құлдырау күтілуде.
Chaos/latency: таймауттарды/ретрайлерді тексеру - жаңа клиент ескі сервердің ең нашар SLA-дан дұрыс өтуі керек.
Canary: жаңа клиенттердің бір бөлігі алдыңғы серверлік нұсқасымен жұмыс істейді - қателер/құлдырау телеметриясын жинаймыз.

Бақылау және операциялық метриктер

Қолдау көрсетілмеген сандар мен олардың автоматты кері қайтарулары бар сұраулар/хабарламалар үлесі.
Клиенттердің нұсқалары бойынша бөлу (User-Agent/метадеректер/claims).
'UNIMPLEMENTED/501/415' қателері және DLQ бағыттары 'unsupported _ feature'.
Деградация уақыты: MGC үшін p95/p99 «кеңейтілген» жауапқа қарсы.

Схемалар тізіліміндегі сыйысымдылық режимдері

FORWARD: жаңа жазба ескі оқырманмен үйлесімді (дефолттар, опциондық).
FULL: и FORWARD, и BACKWARD; жария келісімшарттар үшін қолайлы.
Ұсыным: оқиғалар үшін - BACKWARD-да продюсер мен FORWARD-да (tolerant reader арқылы), сыртқы API үшін - FULL.

Мысалдар

REST (capabilities + деградация)

1. Клиент 'GET/meta/capabilities' → '{"risk_score": false,' price_v2": true} 'жасайды.
2. 'POST/orders' негізгі өрістерді жібереді; 'risk _ score' сұратпайды, себебі сервер оны білмейді.
3. Егер кездейсоқ 'Prefer: include = risk _ score' жіберсе, сервер 'risk _ score' (немесе 'Preference-Applied: none') өрісінсіз 200 жауап береді - клиент құлдырамайды.

gRPC (discovery)

'GetCapabilities ()' әдістер тізімін қайтарды. Клиент 'CaptureV2' дегенді шақырмайды, егер ол жоқ болса, оның орнына 'Capture' дегенді пайдаланады және кіріс деректерін қолдау көрсетілетін түрге дейін жергілікті түрде түрлендіреді.

Events (тізімдегі FORWARD)

Продюсер 'risk _ score' (дефолтпен nullable) өрісін қосты. Ескі консюмер оны елемейді; оның логикасы ядроның тұрақты өрістерін ғана пайдаланады.

Антипаттерндер

Қатты клиент: жауапты whitelist өрістері бойынша сүзгілейді және бейтаныс сипатқа түседі.
Жалған қиял: клиент capabilities тексерусіз жаңа параметрді жібере бастайды.
Желідегі ID/кілттер пішімдерін өзгерту → ескі серверлер/консумерлер жаңа сұрауларды/хабарларды түсінбейді.
enum (default жоқ switch) толық тізімі туралы тігілген болжамдар.
Логикалау ағынды бақылау ретінде: келісім-шарт кодтарының орнына қате жолдарының парсингі.

Енгізу чек-парағы

MGC анықтады; жаңа мүмкіндіктер опциондық ретінде белгіленген.
Capability negotiation (эндпоинт/метадеректер/handshake) сипатталған және іске асырылған.
Клиенттер таныс емес өрістерді елемейді және жаңа enum (fallback) өңдейді.
Қателер келісімшарттары болжамды түрде «қолданылмайды» (HTTP/gRPC/Event).
Схемалар тізілімі тиісті артефактілер үшін FORWARD/FULL теңшелген.
Автотесттер: schema-diff (FORWARD), ескі серверге қарсы клиенттің келісімшарттық тестілері, canary.
Өлшемдер: клиенттің нұсқасы, істен шығу, тозу үлесі, p95 MGC.
Құжаттама/SDK парақтар тізімін және тозу мысалдарын жариялайды.

FAQ

Forward тәжірибеде backward-нан қандай айырмашылығы бар?
Backward: Жаңа сервер ескі клиенттерді бұзбайды. Forward: ескі сервер жаңа клиенттерден (немесе ескі консюмерден - жаңа хабарлардан) бұзылмайды. Сіз full жетесіз.

Әрқашан capabilities енгізу керек пе?
Егер белсенді эволюцияны синхронды релизсіз күтсеңіз - иә. Бұл ондаған major-желілерді ұстаудан арзан.

Қауіпсіздікпен не істеу керек?
Жаңа фичтер жеке scopes/claims талап етуі тиіс. Егер сервер оларды қолдамаса, клиент қауіпсіздікті төмендетпеуі керек, бірақ фичадан бас тартуы керек.

Сервердің нұсқасы бойынша қолдауды «болжауға» бола ма?
Қалаусыз. Анық сұраған дұрыс (capabilities) немесе медиатипке/схемаға қараған дұрыс.

Жиынтығы

Тiкелей үйлесiмдiлiк - бұл мүмкiндiктер туралы келiсу және қауiпсiз деградациялау тәртiбi. Тұрақты ядро, capability negotiation, аддитивті кеңейту және болжамды қателер жаңа клиенттерге және деректерге ескі серверлермен және тұтынушылармен тығыз қарым-қатынас жасауға мүмкіндік береді - жаппай релиздерсіз және түнгі көші-қонсыз.