Sxemalar reyestri va ma’lumotlar evolyutsiyasi

Nima uchun sxemalar reyestri kerak

Sxemalar reyestri - ma’lumotlar kontraktlari (API, voqealar, oqimlar, xabarlar, omborlar) uchun markazlashtirilgan haqiqat manbai bo’lib, quyidagilarni ta’minlaydi:

Oldindan aytib bo’ladigan evolyutsiya: muvofiqlik qoidalari va «sinish» ni avtomatik tekshirish.
Takrorlanuvchanlik va shaffoflik: versiyalar tarixi, kim/qachon/nima uchun o’zgartirildi.
Standartlashtirish: yagona nomlar, xato formatlari, trassirovka maydonlari, PII-belgilar.
CI/CD bilan integratsiya: ishlab chiqarishdan oldin breaking-oʻzgarishlarni bloklash.

Reyestr Protocol-first va shartnomaviy muvofiqlikni bogʻlab, oʻzgarishlarni tez va xavfsiz qiladi.

Formatlar va qo’llanish sohalari

JSON Schema: REST/HTTP foydali yuklar, hujjatlar, konfiguratsiyalar.
Euro: hodisa shinalari (Kafka/Pulsar), compact/evolyutsiya orqali ID maydonlari.
Protobuf: gRPC/RPC, binar samarali, qatʼiy teglar.
GraphQL SDL: turlar va direktivalar sxemasi, «@deprecated» orqali evolyutsiya.
SQL DDL artefakt sifatida: kelishilgan taqdimotlarni (masalan, tashqi vitrinalarni) ehtiyotkorlik bilan qayd etamiz.

💡 Bitta reyestr bir vaqtning o’zida bir nechta turdagi artefaktlarni saqlashi mumkin, ammo alohida muvofiqlik siyosati bilan.

Moslashuv rejimlari

BACKWARD: Yangi sxemalar eski maʼlumotlar/xabarlarni oʻqiydi. Payload’ni qo’shimcha ravishda kengaytiradigan prodyuser uchun mos keladi.
FORWARD: Eski iste’molchilar yangi ma’lumotlarni to’g’ri o’qiydilar (tolerant reader talab qiladi).
FULL: ikkalasini ham birlashtiradi (qattiqroq, ommaviy shartnomalar uchun qulayroq).
NONE: tekshirishsiz - faqat qum qutilari uchun.

Tavsiyalar:

Events: ko’pincha BACKWARD (prodyuser ixtiyoriy ravishda payload kengaytiradi).
Ommaviy API: FULL yoki BACKWARD + mijozlarda qatʼiy tolerant reader.
Ichki prototiplar: vaqtincha NONE, lekin trunk uchun emas.

Xavfsiz (qo’shimcha) vs. xavfli o’zgarishlar

Qo’shimcha (OK):

Ixtiyoriy maydon/turni qoʻshish.
Enumni yangi qiymatlar bilan kengaytirish (agar tolerant reader boʻlsa).
Muqobil proyeksiya/hodisani qoʻshish (’.enriched’).
Cheklovlarni yumshatish (’minLength’,’maximum’↑, lekin ↓ emas).

Xavfli (buziladi):

Maydonlarni olib tashlash/nomini oʻzgartirish yoki ularning turi/majburiyatini oʻzgartirish.
Oqimlardagi maqom/kodek/tartib semantikasini oʻzgartirish.
Protobuf-teglardan qayta foydalanish.
Voqealarda partiyalash kalitini oʻzgartirish.

Reyestrni tashkil etish

Neyming va manzil

Guruhlar/boʻshliqlar:’payments’,’kyc’,’audit’.
’payment. authorized. v1` (events), `payments. v1. CaptureRequest` (gRPC), `orders. v1. Order` (JSON Schema).
Major ismda, minorlar meta-ma’lumotlar/sxema versiyasida.

Meta maʼlumotlar

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

Hayot siklini boshqarish

Draft → Review → Approved → Released → Deprecated → Sunset.
Avtomatlashtirilgan validatorlar/linterlar, qoʻlda yaratilgan design-review (API Guild), release notes.

CI/CDga integratsiya qilish

1. Pre-commit: lokal linterlar (Spectral/Buf/Euro tools).
2. PR-paypline: schema-diff → compatibility mode tekshirish; breakingni bloklaymiz.
3. Artifact publish: kelishilgan sxemani reyestrga kiritish + SDK/modellarni yaratish.
4. Runtime-guard (ixtiyoriy): shlyuz/prodyuser dolzarb sxemaga qarshi payloadni tasdiqlaydi.

PRdagi qadamlar namunasi:

`openapi-diff --fail-on-breaking`
`buf breaking --against
`
`avro-compat --mode BACKWARD`
golden samples ishlab chiqarish va CDC testlarining progoni.

Sxemalar evolyutsiyasi: amaliyotlar

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
Teskari piramida modeli: yadro barqaror, boyitish - yaqin va ixtiyoriy.
major uchun dual-emit/dual-write: parallel ravishda’v1’va’v2’ni nashr etamiz.
Sunset-reja: sana, foydalanish, ogohlantirish, adapterlar.
Tolerant reader: mijozlar nomaʼlum maydonlarga eʼtibor bermaydilar va yangi enumlarni toʻgʻri qayta ishlaydilar.

Sxemalar va tekshirishlar namunalari

JSON Schema (parcha, qoʻshimcha maydon)

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
}

💡 Ixtiyoriy sifatida’risk _ score’qoʻshilgan → BACKWARD mos keladi.

Euro (muvofiqlik uchun 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 (taglarni qayta ishlatmang)

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

Voqealar registri va partiyalashtirish

Hodisaning nomi:’domain. action. v{major}` (`payment. captured. v1`).
Partiyalashtirish kaliti - kontraktning bir qismi (’payment _ id’,’user _ id’).
Core vs Enriched:’.v1’(yadro) va’.enriched. v1’(tafsilotlar).
Reyestrdagi moslik: mavzu/tur darajasidagi rejimlar; CI mos kelmaydigan oʻzgarishlarni rad etadi.

Migratsiyani boshqarish

Expand → Migrate → Contract (REST/gRPC):

1. maydonlarni/jadvallarni qoʻshish; 2) yangi maydonlarni yozishni/o’qishni boshlash; 3) eskisini sunsetdan keyin olib tashlash.

Dual-emit (Events): parallel’v1 ’/’ v2’, konsumer/proyeksiya migratsiyasi, keyin’v1’ni olib tashlash.
Replay: proyeksiyalarni logdan yangi sxemaga qayta yigʻish (faqat moslashuv va migratorlarda).
Adapterlar: murakkab mijozlar uchun’v1 v2’tarjima qiluvchi geytvey/proksi.

Xavfsizlik va komplayens

’x-pii: true’,’x-sensitivity: high’sxemasidagi PII/PCI belgilari.
Kirish siyosati: sxemalarni kim nashr etishi/oʻzgartirishi (RBAC), relizlarni imzolashi mumkin.
Kriptografiya: sxemalar versiyalari imzosi, o’zgarmas audit jurnallari (WORM).
Unutish huquqi: shifrlash/kripto-oʻchirishni talab qiladigan maydonlarni koʻrsating; reyestrdagi guidance.

Kuzatuv va audit

Dashbordlar: oʻzgarishlar soni, turlari (minor/major), rad etilgan PR ulushi, versiyalardan foydalanish.
Audit-trail: sxemani kim o’zgartirdi, PR/ADR havolalari, bog’langan reliz.
Runtime-metriklar: validatsiyadan o’tmagan xabarlar foizi; muvofiqlik hodisalari.

Asboblar (namunaviy stek)

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.
Reyestrlar/kataloglar: Artifact Registry, Git-based registry, Backstage Catalog, custom UI.
Hujjatlar: Redocly/Stoplight, Swagger-UI, GraphiQL.

Antipatternlar

Swagger-wash: sxema xizmatning haqiqatini aks ettirmaydi (yoki aksincha).
O’chirilgan muvofiqlik tekshiruvi: «shoshilinch» → prod buziladi.
Protobuf teglarini qayta ishlatish: maʼlumotlarning jimgina buzilishi.
«Hamma narsa uchun» yagona moslashuv rejimi: turli domenlar turli xil rejimlarni talab qiladi.
Xom CDClar ommaviy sxemalar sifatida: DD modelining chiqib ketishi, evolyutsiyaning mumkin emasligi.

Joriy etish chek-varaqasi

Artefaktlar formati va domenlar boʻyicha compatibility mode aniqlandi.
Linterlar va schema-diff CI uchun sozlangan, PR breaking paytida bloklanadi.
Mijozlarda tolerant reader yoqilgan;’additionalProperties = true’(oʻrinli).
Asosiy o’zgarishlar RFC/ADR orqali amalga oshiriladi, sunset-reja va dual-emit/dual-write mavjud.
Sxemalar PII/PCI va kirish darajalari bilan belgilanadi; audit kiritilgan.
Moslik versiyalari va nosozliklaridan foydalanish bo’yicha dashbordlar.
Reyestrdan SDK/modellarni yaratish payplaynning bir qismidir.
Hujjatlar va golden samples avtomatik ravishda yangilandi.

FAQ

Registrsiz sxemalarni Git’da saqlash mumkinmi?
Ha, lekin reyestr uyg’unlik, qidiruv, meta ma’lumotlar, markazlashtirilgan siyosat va «on-the-fly» validatsiyasini qo’shadi. Eng yaxshi variant - Git storage + UI/ustidagi siyosatlar.

Moslashuv rejimini qanday tanlash mumkin?
O’zgarishlar yo’nalishiga qarang: agar prodyuser payload - BACKWARD ni kengaytirsa. Ommaviy API/SDK uchun - FULL. Tezkor prototiplar uchun - vaqtincha NONE (trunk uchun emas).

Agar kerak boʻlsa, nima qilish kerak?
v2: dual-emit/dual-run, sunset-sanalar, adapterlar, foydalanish telemetriyasi, migratsiya gaydalarini tayyorlaymiz.

Payloadni ijarada tasdiqlash kerakmi?
Tanqidiy domenlar uchun - ha: bu «axlat» xabarlarining oldini oladi va diagnostikani tezlashtiradi.

Jami

Sxemalar reyestri ma’lumotlar evolyutsiyasini xavfli improvizatsiyadan boshqariladigan jarayonga aylantiradi: yagona muvofiqlik qoidalari, avtomatik tekshiruvlar, tushunarli versiyalar va shaffof tarix. Unga additive-first, tolerant reader, dual-emit va sunset intizomini qo’shing - va shartnomalaringiz tez rivojlanadi, sinish va tungi hodisalarsiz.