Sxemlərin reyestri və məlumatların təkamülü

Niyə sxemlərin reyestri lazımdır

• Proqnozlaşdırıla bilən təkamül: uyğunluq qaydaları və avtomatik sınaq.
• Təkrarlanabilirlik və şəffaflıq: versiyalar tarixi, kim/nə vaxt/nə üçün dəyişdi.
• Standartlaşdırma: vahid adlar, səhv formatları, izləmə sahələri, PII işarələri.
• CI/CD ilə inteqrasiya: istehsal əvvəl breaking-dəyişikliklər kilidi.

Reyestr Protocol-first və müqavilə uyğunluğunu birləşdirir, dəyişiklikləri sürətli və təhlükəsiz edir.

Formatlar və tətbiq sahələri

JSON Schema: REST/HTTP yük, sənədlər, konfiqurasiyalar.
Avro: hadisə şinləri (Kafka/Pulsar), kompakt/təkamül ID sahələri vasitəsilə.
Protobuf: gRPC/RPC, binar effektiv, sərt etiketlər.
GraphQL SDL: tip sxemi və direktivlər, '@deprecated' vasitəsilə təkamül.
SQL DDL bir artefakt kimi: razılaşdırılmış təqdimatları (məsələn, xarici vitrinlər) qeyd edirik - ehtiyatla.

Uyğunluq rejimləri

BACKWARD: Yeni sxemlər köhnə məlumat/mesajları oxuyur. Payload additiv genişləndirən prodüser üçün uyğundur.
FORWARD: Köhnə istehlakçılar yeni məlumatları düzgün oxuyurlar (tolerant reader tələb edir).
FULL: Hər ikisini birləşdirir (daha sərt, ictimai müqavilələr üçün daha əlverişlidir).
NONE: yoxlama olmadan - yalnız qum qutuları üçün.

• Events: daha tez-tez BACKWARD (prodüser payload əlavə edir).
• Public API: TAM və ya BACKWARD + müştərilərdə ciddi tolerant reader.
• Daxili prototiplər: müvəqqəti NONE, lakin trunk deyil.

Təhlükəsiz (additiv) vs. təhlükəli dəyişikliklər

• Əlavə sahə/tip əlavə edin.
• Yeni dəyərlərlə enum genişləndirilməsi (tolerant reader ilə).
• Alternativ proyeksiyanın/hadisənin əlavə edilməsi ('.enriched').
• Məhdudiyyətlərin yumşaldılması ('minLength', 'maximum' ↑, lakin ↓ deyil).

• Sahələrin silinməsi/adının dəyişdirilməsi və ya onların növünün/öhdəliyinin dəyişdirilməsi.
• Status semantikasının/kodeklərin/sıra axınlarının dəyişdirilməsi.
• Protobuf etiketlərinin yenidən istifadəsi.
• Hadisələrdə partizan açarının dəyişdirilməsi.

Reyestrin təşkili

Neyminq və ünvan

Qruplar/məkanlar: 'payments', 'kyc', 'audit'.
Adları: 'payment. authorized. v1` (events), `payments. v1. CaptureRequest` (gRPC), `orders. v1. Order` (JSON Schema).
Major adında, minor - metadata/sxem versiyasında.

Metadata

'owner' (komanda), 'domain', 'slas' (SLO/SLA), 'security. tier` (PII/PCI), `retention`, `compatibility_mode`, `sunset`, `changelog`.

Həyat dövrünün idarə edilməsi

Draft → Review → Approved → Released → Deprecated → Sunset.
Avtomatik validatorlar/linterlər, əl design-review (API Guild), release notes.

CI/CD-yə inteqrasiya

1. Pre-commit: lokal linterlər (Spectral/Buf/Euro tools).
2. PR-paypline: schema-diff → yoxlama compatibility mode; breaking bloklayın.
3. Artifact publish: reyestrdə razılaşdırılmış sxem + SDK/modellərin yaradılması.
4. Runtime-guard (isteğe bağlı): Şluz/prodüser cari sxemə qarşı payload təsdiqləyir.

• `openapi-diff --fail-on-breaking`
• `buf breaking --against
  `
• `avro-compat --mode BACKWARD`
• qızıl samples generation və CDC testlər qaçış.

Sxemlərin təkamülü: təcrübələr

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
Əks piramida modeli: nüvə stabil, zənginləşdirmə - yaxınlıqda və isteğe bağlıdır.
major üçün dual-emit/dual-write: paralel olaraq 'v1' və 'v2' dərc edirik.
Sunset planı: tarixlər, istifadə, xəbərdarlıqlar, adapterlər.
Tolerant reader: Müştərilər naməlum sahələrə məhəl qoymur və yeni enumları düzgün emal edirlər.

Sxemlər və yoxlamalar nümunələri

JSON Sxema (fraqment, əlavə sahə)

json
{
"$id": "orders.v1.Order",
"type": "object",
"required": ["id", "status"],
"properties": {
"id": { "type": "string", "format": "uuid" },
"status": { "type": "string", "enum": ["created", "paid", "shipped"] },
"risk_score": { "type": "number", "minimum": 0, "maximum": 1 }
},
"additionalProperties": true
}

Avro (uyğunluq üçün default)

json
{
"type": "record",
"name": "PaymentAuthorized",
"namespace": "payment.v1",
"fields": [
{ "name": "payment_id", "type": "string" },
{ "name": "amount", "type": "long" },
{ "name": "currency", "type": "string" },
{ "name": "risk_score", "type": ["null", "double"], "default": null }
]
}

Protobuf (etiketləri təkrar istifadə etməyin)

proto syntax = "proto3";
package payments.v1;

message CaptureRequest {
string payment_id = 1;
int64 amount = 2;
string currency = 3;
optional double risk_score = 4; // additive
}
// tag=4 зарезервирован под risk_score, его нельзя менять/удалять без v2

Hadisə reyestri və partizanlaşdırma

Hadisələrin adlandırılması: 'domain. action. v{major}` (`payment. captured. v1`).
Partizan açarı - müqavilənin bir hissəsidir ('payment _ id', 'user _ id').
Core vs Enriched: '.v1' (nüvə) və '.enriched. v1 '(detallar).
Reyestrdə uyğunluq: mövzu/tip səviyyəsində rejimlər; CI uyğun olmayan dəyişiklikləri rədd edir.

Miqrasiya menecmenti

1. sahələr/cədvəllər əlavə edin; 2) yeni sahələr yazmağa/oxumağa başlamaq; 3) sunset sonra köhnə aradan qaldırılması.

• Dual-emit (Events): paralel 'v1 '/' v2', konsumer/proyeksiyaların miqrasiyası, sonra 'v1' çıxarılması.
• Replay: log proyeksiyalarının yeni sxemə yenidən yığılması (yalnız uyğunluq və miqratorlarda).
• Adapterlər: mürəkkəb müştərilər üçün 'v1 v2' tərcümə gateway/proxy.

Təhlükəsizlik və uyğunluq

Sxemdə PII/PCI etiketləri: 'x-pii: true', 'x-sensitivlik: high'.
Giriş siyasəti: kim çap/sxemləri dəyişdirmək (RBAC), buraxılışları imzalamaq.
Kriptoqrafiya: sxem versiyalarının imzası, dəyişməz audit jurnalları (WORM).
Unudulmaq hüququ: şifrələmə/kriptovalyuta tələb edən sahələri göstərin; reyestrdə guidance.

Müşahidə və audit

Daşbordlar: dəyişikliklər sayı, növləri (minor/major), rədd edilmiş PR payı, versiyaların istifadəsi.
Audit Trail: Kim sxemi dəyişdi, PR/ADR linkləri, Release bağlı.
Runtime-metriklər: təsdiqlənməyən mesajların faizi; uyğunluq hadisələri.

Alətlər (təqribən yığın)

OpenAPI/JSON Schema: Spectral, OpenAPI Diff, Schemathesis.
Protobuf/gRPC: Buf, buf-breaking, protoc linters.
Avro/Events: Confluent/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: GraphQL Inspector, GraphQL Codegen.
Reyestrlər/kataloqlar: Artifact Registry, Git-based registry, Backstage Catalog, custom UI.
Sənədləşmə: Redocly/Stoplight, Swagger-UI, GraphiQL.

Antipatternlər

Swagger-wash: sxem xidmətin reallığını əks etdirmir (və ya əksinə).
Bağlanan uyğunluq testi: «təcili lazımdır» → prod qırılır.
Protobuf etiketlərinin yenidən istifadəsi: məlumatların sakit pozulması.
«Hər şey üçün» vahid uyğunluq rejimi: müxtəlif domenlər fərqli rejimlər tələb edir.
İctimai sxemlər kimi xam CDC: DB modelinin xaricə sızması, təkamülün mümkünsüzlüyü.

Giriş çek siyahısı

• Domenlər üzrə artefaktların formatı və compatibility mode müəyyən edilmişdir.
• CI-də linterlər və schema-diff konfiqurasiya, PR breaking zaman bloklanır.
• Müştərilərdə tolerant reader aktiv; 'additionalProperties = true' (uyğun olduqda).
• Əsas dəyişikliklər RFC/ADR-dən keçir, sunset planı və dual-emit/dual-write var.
• Sxemlər PII/PCI və giriş səviyyələri ilə qeyd olunur; audit daxildir.
• Uyğunluq versiyalarının istifadəsi və uğursuzluqları üçün daşbordlar.
• SDK/modellərin reyestrdən yaradılması paylaynın bir hissəsidir.
• Sənədlər və golden samples avtomatik olaraq yenilənir.

FAQ

Reyestr olmadan - sxemləri Git-də saxlamaq mümkündürmü?
Bəli, lakin reyestr API uyğunluq, axtarış, meta-məlumat, mərkəzləşdirilmiş siyasət və «on-the-fly» validasiya əlavə edir. Ən yaxşı variant - Git storage + UI/siyasətlər.

Uyğunluq rejimini necə seçmək olar?
Dəyişikliklərin istiqamətinə baxın: əgər prodüser payload - BACKWARD-ı genişləndirirsə. İctimai API/SDK üçün - FULL. Sürətli prototiplər üçün - müvəqqəti NONE (trunk deyil).

Lazım olduqda nə etmək lazımdır?
v2 hazırlayırıq: dual-emit/dual-run, sunset-tarixlər, adapterlər, istifadə telemetriyası, miqrasiya qaydaları.

Payload-ı rentaymda təsdiqləmək lazımdırmı?
Kritik domenlər üçün - bəli: bu, «zibil» mesajlarının qarşısını alır və diaqnozu sürətləndirir.

Yekun

Sxemlərin reyestri məlumatların təkamülünü riskli improvizasiyadan idarə olunan prosesə çevirir: vahid uyğunluq qaydaları, avtomatik yoxlamalar, başa düşülən versiyalar və şəffaf tarix. Ona additive-first, tolerant reader, dual-emit və sunset intizamını əlavə edin - və müqavilələriniz tez, heç bir pozulma və gecə hadisələri olmadan inkişaf edəcək.