API müqavilə uyğunluğu

Niyə müqavilə uyğunluğu lazımdır

Müqavilə uyğunluğu API-nin mövcud inteqrasiyaları pozmadan inkişaf etmək qabiliyyətidir. Artan API sistemlərində müştərilərin kodu daha tez-tez dəyişir; Uyğunluq, «böyük keçidlər» təşkil etmədən fitzləri iterativ şəkildə buraxmağa imkan verir.

Əsas fikir: müqavilə birincidir, dəyişikliklər uyğunluq qaydalarına uyğun olaraq aparılır və avtomatik yoxlanılır.

Əsas anlayışlar

Müqavilə - rəsmi interfeys spesifikasiyası: resurslar/metodlar/hadisələr, məlumat sxemləri, səhv kodları, limitlər, SLA, təhlükəsizlik tələbləri.
Təchizatçı (provider) - API sahibi. İstehlakçı (consumer) - müştəri/inteqrasiya.

• Backward: Yeni təchizatçı köhnə istehlakçılarla işləyir.
• Forward: köhnə təchizatçı yeni istehlakçılarla işləyir (adətən «dözümlü oxucular» tərəfindən əldə edilir).
• Full: həm backward, həm də forward (ən güclü variant).
• Additivlik - mövcud elementləri qırmadan isteğe bağlı elementlərin əlavə edilməsi.

Version siyasəti

• MAJOR - pozucu dəyişikliklər (yalnız yeni API xətti: '/v2 ',' service. v2`).
• MINOR - əlavə dəyişikliklər (yeni isteğe bağlı sahələr/metodlar).
• PATCH - müqaviləni dəyişdirmədən düzəlişlər.
• Deprecation Policy: köhnəlmiş elementlərin elanı, dəstək pəncərəsi (sunset), başlıqlarda/metadata xəbərdarlıqları, çıxarılma planı.

Təhlükəsiz vs təhlükəli dəyişikliklər

Təhlükəsiz (adətən backward-compatible)

JSON/Protobuf/Avro-a isteğe bağlı sahə əlavə edin.
Yeni bir end-point/metod/hadisə əlavə edin.
İstehlakçılar naməlum dəyərlərə dözümlü olduqda yeni dəyərlərlə enum genişləndirilməsi.
Limitlərin artırılması (məsələn, 'maxItems') minimum sərtləşdirilmədən.
Düzgün defolt ilə nullable əlavə.
Təsvirin/nümunələrin mətninin dəyişdirilməsi.

Təhlükəli (uyğunluq pozur)

Sahələrin adının dəyişdirilməsi/silinməsi, onların növünün və ya öhdəliyinin dəyişdirilməsi.
Status-kodların/səhvlərin semantikasının dəyişdirilməsi (məsələn, '200', '204' və ya '404').
ID formatının dəyişdirilməsi (UUID → int).
Versiyası olmadan sərtləşdirilmiş validasiya (daha sərt minimumlar/nümunələr).
gRPC axınlarında/hadisələrində sıra və strukturun dəyişdirilməsi.
Yeni sahələr üçün Protobuf etiket nömrələrini yenidən istifadə edin.

Qarşılıqlı üslub uyğunluğu

REST/HTTP + JSON Schema

Additivlik: Yeni sahələr 'optional '/' nullable' kimi qeyd olunur.
Müştəridə Tolerant Reader: naməlum sahələrə məhəl qoymayın; əmrə güvənməyin.
Version: major - yolda ('/v2 ') və ya mediatipdə (' application/vnd. example. v2+json`).
ETag/If-Match: qaçışsız təhlükəsiz yeniləmələr üçün.
Səhvlər: vahid format ('type', 'code', 'title', 'detail', 'trace _ id'), major olmadan 'code' dəyərlərini dəyişdirməyin.
Pagination: kursorlar offset üstünlük; 'next _ cursor' sahələrini əlavə edin, mövcud olanların mənasını dəyişdirməyin.

gRPC / Protobuf

Etiketlərin nömrələnməsi dəyişməz olaraq qalır. Silinmiş etiketlər yenidən istifadə edilmir.
Yeni sahələr - 'optional '/' repeated' serverdə ağlabatan defoltlarla.
streaming-RPC-də mesajların qaydasını və məcburiyyətini dəyişdirməyin.
Səhvlərin statusu sabitdir ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' və s.); yeni semantika → metodun/xidmətin yeni versiyası.

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON Schema

Hadisələrin adlandırılması: 'domain. action. v{major}`.
Yeni sahələr - opsiyonel; nüvə və zənginləşdirmə ('.enriched') ayırın.
Sxem qeydləri: mövzu/hadisə üzrə uyğunluq qaydaları (BACKWARD/FORWARD/FULL).
Enum genişləndirilməsi istehlakçıların tərəfində tolerant reader ilə icazə verilir.
Vahid üçün partizan açarının/sifarişin dəyişdirilməsi = pozucu dəyişikliklər.

GraphQL

Sahələrin/növlərin əlavə edilməsi - təhlükəsiz; silinməsi/adının dəyişdirilməsi - yalnız @deprecated və miqrasiya pəncərəsi vasitəsilə.
Major olmadan növləri dəyişdirməyin/nullable deyil.
complexity/depth nəzarət - limitlər müqavilənin bir hissəsidir.

Davamlı təkamül nümunələri

Additive-first: sındırmadan genişləndirin.
Capability negotiation: Müştərilər dəstəklədiklərini bildirirlər (başlıqlar/parametrlər/razılaşmalar), server uyğunlaşır.
Müqavilə sərhədləri: MGC-ni (minimum zəmanət müqaviləsi) düzəldin və genişləndirmələri (əks piramida modeli) ayırın.
Tolerance by default: Müştərilər həddindən artıq əhəmiyyət vermirlər və naməlum enum (fallback) dəyərlərini düzgün idarə edirlər.
Dual-write/Dual-emit: major dəyişikliklər zamanı bir müddət paralel olaraq 'v1' və 'v2' buraxın.
Sunset headers/Events: versiyaların çıxarılması barədə əvvəlcədən məlumat verin.

Governance və avtomatlaşdırma

• OpenAPI/Spectral: adlandırma, paginasiya, səhv kodları, sahə formatları.
• Buf/Protobuf: etiketlərin yenidən istifadəsinin qadağan edilməsi, paketlərin notasiyası.
• AsyncAPI/Schema Registry: CI səviyyəsində sxemlərin uyğunluğu.
• Müqavilə kataloqu (SSOT): diff tarixi olan sxemlərin/versiyaların mərkəzləşdirilmiş reyestri.
• API Guild: qaydaları, şablonları və dəyişikliklər review qəbul Guild/komitə.
• Change Management: RFC/ADR, release notes, miqrasiya qaydaları.

Uyğunluq testi

CI-də Schema-diff: sındırıcı spec dəyişikliklərini bloklayırıq (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Pact/oxşar - müəyyən istehlakçıların müqavilələrinə qarşı təchizatçının yoxlanılması.
Golden samples: referans sorğular/cavablar və reqressiya üçün hadisələr.
E2E Canary: payına/ayrı-ayrı konsumer qrupları.
Chaos/latency: zaman/retraut testi - latency-SLO dəyişikliyi müqavilə dəyişikliyi hesab olunur.

Miqrasiya və Deprekeyt

1. Deprekeyt elan edin: elementi qeyd edin, sunset müddətini və alternativini qeyd edin.
2. Uyğunluq müddətini saxlayın: dual-write/dual-emit, körpülər, adapterlər.
3. Telemetriya toplayın: daha kim köhnə istifadə edir?
4. Rabitə: poçt, buraxılış notları, test stendləri.
5. Çıxarılması: pəncərədən sonra - sabit buraxılış ilə çıxarılması.

Dəyişiklik nümunələri

REST

json
{ "id":"p1", "status":"authorized" }

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Naməlum sahələrə məhəl qoymayan müştərilər qırılmır.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

`payment. authorized. v1 '(nüvə) +' payment. enriched. v1 '(zənginləşdirmə). Kritik yol istehlakçıları nüvəni oxuyurlar və zənginləşdirmədən asılı deyillər.

Antipatternlər

Swagger-wash: spesifikasiya formal olaraq mövcuddur, lakin xidmətin davranışı ondan fərqlidir.
Breaking by stealth: Yeni versiya və miqrasiya pəncərəsi olmadan növü/statusu/formatı dəyişdi.
Xam CDC-hadisələr ictimai müqavilə kimi: DD sxemlərinin sızması, təkamülün mümkünsüzlüyü.
Sərt müştəri: naməlum sahələrdə/dəyərlərdə düşür; tolerant reader yoxdur.
Protobuf etiketlərinin yenidən istifadəsi: məlumatların sakit korrupsiyası.
Gecikmə «müqaviləsiz» kimi: gözlənilmədən p95 uzadıldı - istehlakçılar taymautlarda pozulur.

Check-list uyğunluq (merj əvvəl)

• Dəyişikliklər əlavə (və ya əsas versiyası hazırlanmışdır).
• Linters/diff çekləri keçdi, uyğunluq qaydaları yaşıl.
• Səhvlər/kodlar/statuslar semantikanı dəyişmədi.
• Enum köhnə dəyərləri qadağan etmədən genişləndirilir; müştərilər tolerantdır.
• MGC sərhədləri dəyişməz.
• Yenilənmiş nümunələr/sənədlər/SDK.
• Major üçün - plan dual-write/dual-emit, sunset-date, komm-plan.
• Testlər CDC/Golden/E2E keçdi.

FAQ

Backward forward uyğunluğundan nə ilə fərqlənir?
Backward - yeni serverlər köhnə müştəriləri sındırmır. Forward - yeni müştərilər köhnə serverlərdə pozulmur (tolerant reader və səliqəli defoltlar vasitəsilə).

'/v2 'nə vaxt etmək lazımdır?
Alternativlər/semantika dəyişdikdə, sahələr/metodlar silinir, yeni bir təhlükəsizlik modeli tələb olunur - yeni bir xətt açmaq daha asan və dürüst olur.

Schema Registry/lintersiz yaşaya bilərəmmi?
Nəzəri olaraq - bəli, praktiki olaraq - bunlar tez-tez reqressiyalar və «gizli» qırılmalardır. Avtomatlaşdırma ödəyir.

Enum genişləndirilə bilər?
Bəli, müştərilər naməlum dəyərləri düzgün emal edirlərsə (fallback/ignore). Əks halda - major.

Yekun

Müqavilə uyğunluğu qaydalar + nizam-intizam + avtomatlaşdırmadır. Əlavə dizayn edin, pozucu dəyişiklikləri verin, tolerant reader tətbiq edin, diffləri və CDC-ləri avtomatik yoxlayın, deprekeyti planlaşdırın. Beləliklə, API-lər sürətlə inkişaf edə, inteqrasiyalar isə sabit qala biləcəklər.