Birbaşa uyğunluq

Birbaşa uyğunluq nədir

Birbaşa uyğunluq (forward compatibility) - sistemin əvvəlcə nəzərdə tutulduğundan daha yeni müştərilərlə və ya məlumatlarla düzgün işləmək qabiliyyətidir. Daha asan: köhnə server ona yeni müştəri gələndə qırılmır; köhnə istehlakçı yeni bir mesaj ilə qarşılaşdıqda düşmür.

Əks uyğunluq (yeni sistem köhnə müştəriləri dəstəklədiyi zaman) forward məsuliyyət istiqaməti ilə fərqlənir: biz protokolları və müştəriləri bütün ekosistemin ümumi yenilənməsi olmadan gələcək genişləndirmələri «yaşamaq» üçün dizayn edirik.

Əsas prinsiplər

1. Tolerant reader & tolerant writer

Reader naməlum sahələrə/başlıqlara məhəl qoymur və düzgün fallback ilə yeni enum dəyərlərinə imkan verir.
Writer server açıq dəstəklənən (capabilities) elan deyil ki, heç bir şey göndərir.

2. Capability negotiation

Handshake mərhələsində açıq fürsət mübadiləsi (fiçlər/versiyalar/media növləri). Müştəri öz davranışını server cavabına uyğunlaşdırır.

3. Defolt deqradasiyası

Yeni imkanlar opsionaldır: server/konsumer onları dəstəkləmirsə, ssenari yenə də faydalı minimum (MGC) ilə başa çatacaq.

4. Sabit Nüvə (MGC)

Minimum zəmanət müqaviləsi dəyişməz; yeniliklər genişlənmə kimi yaşayır.

5. Protokol hissəsi kimi səhv müqavilələri

Proqnozlaşdırıla bilən kodlar/səbəblər («fayl dəstəklənmir», «media növü bilinmir») müştəriyə avtomatik olaraq dəstəklənən rejimə geri dönməyə imkan verir.

6. Sürprizsiz versiyalar

Major xətləri ayrılır; kiçik uzantıları server/konsumer yeniləmə tələb etmir.

Harada xüsusilə vacibdir

Uzunmüddətli inteqrasiya ilə ictimai API (tərəfdaşlar, mobil tətbiqlərdə SDK).
Bir çox müstəqil konsumer ilə hadisə platformaları.
Arxa plandan daha yavaş yenilənən mobil müştərilər.
Edge/IoT, harada cihaz parkının bir hissəsi nadir hallarda tikilir.

Stillərə uyğun satış nümunələri

REST/HTTP

• 'Accept '/parametrləri olan mediatiplər (' application/vnd. example. order+json; v=1; profile=risk`).
• 'Prefer: include =...' isteğe bağlı bloklar üçün.
• Başlıq 'X-Capabilities: risk_score,item_details_v2'.

• Əsas formatda sorğu göndərir, uzantılar - yalnız server capability (OPTIONS/desc/lead-end point vasitəsilə) təsdiq etdikdə.
• «415/406/501» avtomatik olaraq dəstəklənən format/metoda geri dönür.
• Server cavabı: naməlum parametrlər - məhəl qoymayın; əlavə sahələr - icazə verilir; səhv formatı sabitdir ('type/code/detail/trace _ id').

gRPC / Protobuf

Sabit xidmətlər: yeni metodlar/sahələr - əlavə; köhnə server sakitcə naməlum sorğu sahələrinə məhəl qoymur.
Feature discovery: 'GetCapabilities ()' metodu fich/limit siyahılarını qaytarır. Server elan etmədikdə müştəri «v2 metodu» çağırmır.
Streaming: minimum mesaj dəstinin qaydasını qeyd edin; köhnə müştərinin görməməzlikdən gəldiyi yeni «çərçivələr» uzantıları/növləri ilə işarə edin.

GraphQL

Forward-friendly: Yeni sahələr/tiplər serverdə görünür - köhnə müştərilər sadəcə onları tələb etmir.
Təxminlər qadağandır: müştəri sxemi (introspektsiya/kodogen) saxlamalı və naməlum direktivləri/dəyişənləri göndərməməlidir.
Deqradasiya: server xüsusi direktiv/feature bilmirsə - müştəri onsuz sorğu qurur.

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

Reyestrdə FORWARD-uyğunluq sxemi: Köhnə konsumerlər yeni sxemlə yazılmış mesajları oxuya bilərlər.
Defoltları olan əlavə sahələr: yeni prodüserlər köhnə konsumerləri sındırmır.
Core vs Enriched: nüvə eyni qalır, yeni məlumatlar '.enriched' və ya isteğe bağlı sahələr kimi dərc olunur.

Dizayn təcrübələri

1. Minimum Sorğu Müqaviləsi (MGC)

Əməliyyat uzun illər bütün serverlər tərəfindən dəstəklənən «dar boyun» olmalıdır.

2. Müqavilə səviyyəsində fiça bayraqları

Fiçləri adlandırılmış imkanlar kimi təsvir edin: 'risk _ score', 'pricing _ v2', 'strong _ idempotency'. Müştəri onları açıq şəkildə daxil edir.

3. «Dəstəklənmir» üçün açıq səhv kodları

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

4. Sifariş/tam siyahılara etibar etməyin

Müştəri yeni enum dəyərlərinə, yeni sahələrin olmamasına və «əlavə» xüsusiyyətlərə hazır olmalıdır.

5. Sabit identifikatorlar və formatlar

Xətt daxilində partizan ID/açar formatını dəyişdirməyin - bu oxucuların tərəfində forward pozur.

6. «Maşın oxunan» sənədləşmə

Descriptors hosting: OpenAPI/AsyncAPI/Proto descriptors/GraphQL SDL. Müştərilər phich dəstək müqayisə edə bilər.

Forward uyğunluq testi

Schema-diff FORWARD/FULL rejimində: yeni sxem köhnə istehlakçını/serverini təsdiqləyir.
Müştərinin müqavilə testləri: Yeni müştəri köhnə serverə qarşı çalışır.
Golden requests: «köhnə» server vasitəsilə «yeni» sorğular dəsti; kritik səhvlər olmadan deqradasiya gözlənilir.
Chaos/latency: Zaman/retraj yoxlaması - yeni müştəri köhnə serverin ən pis SLA-sından sağ çıxmalıdır.
Canary: Yeni müştərilərin bir hissəsi əvvəlki server versiyası ilə işləyir - səhv/deqradasiya telemetriyasını toplayırıq.

Müşahidə və əməliyyat metrikası

Dəstəklənməmiş fiçalar və onların avtomatik geri qaytarılması ilə sorğuların/mesajların payı.
Müştərilərin versiyalarına görə paylanması (User-Agent/metadata/claims).
'UNIMPLEMENTED/501/415' səhvləri və 'unsupported _ feature' ilə DLQ marşrutları.
Deqradasiya vaxtı: «qabaqcıl» cavab qarşı MGC üçün p95/p99.

Sxem reyestrində uyğunluq rejimləri

FORWARD: Yeni yazı köhnə oxucu ilə uyğundur (defolt, opsionallıq lazımdır).
FULL: и FORWARD, и BACKWARD; ictimai müqavilələr üçün əlverişlidir.
Tövsiyə: hadisələr üçün - prodüserdə BACKWARD və konsumerdə FORWARD (tolerant reader vasitəsilə), xarici API üçün - FULL.

Nümunələr

REST (capabilities + deqradasiya)

1. Müştəri 'GET/meta/capabilities '→ '{«risk_score": false, «price_v2": true}' edir.
2. 'POST/orders' əsas sahələri göndərir; 'risk _ score' tələb etmir, çünki server bunu bilmir.
3. Təsadüfən 'Prefer: include = risk _ score' göndərilsə, server 'risk _ score' (və ya 'Preference-Applied: none') sahəsi olmadan 200 cavab verir - müştəri düşmür.

gRPC (discovery)

'GetCapabilities ()' metod/fich siyahısını qaytardı. Müştəri «CaptureV2» çağırmır - bunun əvəzinə «Capture» istifadə edir və yerli olaraq giriş məlumatlarını dəstəklənən görünüşə çevirir.

Events (reyestrdə FORWARD)

Prodüser 'risk _ score' (defolt ilə nullable) sahəsini əlavə etdi. Köhnə konsumer ona məhəl qoymur; Onun məntiqi yalnız sabit nüvə sahələrindən istifadə edir.

Antipatternlər

Sərt müştəri: whitelist sahələrinə cavab süzür və naməlum xüsusiyyətə düşür.
Gizli Fix: Müştəri capabilities yoxlamadan yeni bir parametr göndərməyə başlayır.
Xətt daxilində ID/açar formatlarının dəyişdirilməsi → köhnə serverlər/konsumerlər yeni sorğuları/mesajları anlamağı dayandırırlar.
Tam enum (default olmadan switch) siyahısı haqqında dikilmiş fərziyyələr.
Loging axını nəzarət kimi: müqavilə kodları əvəzinə xəta sətirləri parsing.

Giriş çek siyahısı

• MGC tərəfindən müəyyən edilmişdir; Yeni imkanlar opsiyonel kimi qeyd olunur.
• Capability negotiation (end point/metadata/handshake) təsvir və həyata keçirilmişdir.
• Müştərilər tanış olmayan sahələrə məhəl qoymur və yeni enum (fallback) ilə düzgün məşğul olurlar.
• Səhv müqavilələri əvvəlcədən «dəstəklənmir» (HTTP/gRPC/Event).
• Sxemlərin reyestri müvafiq artefaktlar üçün FORWARD/FULL-də qurulmuşdur.
• Avtotestlər: schema-diff (FORWARD), köhnə serverə qarşı müştərinin müqavilə testləri, canary.
• Metrik: müştəri versiyası, pozulma, deqradasiya payı, p95 MGC.
• Sənədlər/SDK fich siyahısını və deqradasiya nümunələrini dərc edir.

FAQ

Forward praktikada backwarddan nə ilə fərqlənir?
Backward: yeni server köhnə müştəriləri qırmır. Forward: köhnə server yeni müştərilərdən (və ya köhnə müştəri - yeni mesajlardan) pozulmur. İdeal olaraq full-ə çatırsınız.

Həmişə capabilities tətbiq etmək lazımdırmı?
Sinxron buraxılışsız aktiv təkamül gözləyirsinizsə, bəli. Bu major xətləri onlarla saxlamaq daha ucuzdur.

Təhlükəsizlik haqqında nə demək olar?
Yeni xüsusiyyətlər fərdi scopes/claims tələb etməlidir. Əgər server onları dəstəkləmirsə, müştəri təhlükəsizliyi azaltmamalı, fiçadan imtina etməlidir.

Server dəstəyi «təxmin etmək» mümkündürmü?
Arzuolunmaz. Açıq şəkildə soruşmaq (capabilities) və ya media/sxemə baxmaq daha yaxşıdır.

Yekun

Birbaşa uyğunluq, imkanlar barədə razılığa gəlmək və təhlükəsiz şəkildə pozulmaq üçün bir nizam-intizamdır. Sabit nüvə, capability negotiation, əlavə uzantıları və proqnozlaşdırıla bilən səhvlər yeni müştərilərə və məlumatlara köhnə serverlər və istehlakçılarla - kütləvi buraxılışlar və gecə miqrasiyaları olmadan uyğunlaşmağa imkan verir.