Схемалар тізілімі және деректер эволюциясы

Схемалар тізілімі не үшін қажет

Схемалар тізілімі - бұл деректер келісімшарттары (API, оқиғалар, ағындар, хабарламалар, қоймалар) үшін орталықтандырылған ақиқат көзі, ол:

Болжамды эволюция: үйлесімділік ережелері және «сынықтарды» автоматты түрде тексеру.
Қайталану және ашықтық: нұсқалар тарихы, кім/қашан/неліктен өзгертті.
Стандарттау: бірыңғай атаулар, қателер пішімдері, трассировка өрістері, PII-белгілер.
CI/CD біріктіру: breaking-өзгерістерді шығарылғанға дейін бұғаттау.

Тізілім Protocol-first және келісімшарт сыйысымдылығын байланыстырып, өзгерістерді жылдам және қауіпсіз етеді.

Пішімдер және қолдану аясы

JSON схемасы: REST/HTTP пайдалы жүктемелер, құжаттар, конфигурациялар.
Euro: оқиға шиналары (Kafka/Pulsar), compact/ID өрісі арқылы эволюция.
Protobuf: gRPC/RPC, бинарлық тиімді, қатаң тегтер.
GraphQL SDL: түрлер мен директивалардың схемасы, «@deprecated» арқылы эволюция.
SQL DDL артефакт ретінде: келісілген көріністерді (мысалы, сыртқы сөрелерді) сақтықпен бекітеміз.

💡 Бір тізілім бірден артефактілердің бірнеше түрін сақтай алады, бірақ бөлек үйлесімділік саясатымен.

Сыйысымдылық режимдері

BACKWARD: жаңа схемалар ескі деректерді/хабарларды оқиды. Payload аддитивті кеңейтетін продюсер үшін қолайлы.
FORWARD: ескі тұтынушылар жаңа деректерді дұрыс оқиды (толерант reader талап етеді).
FULL: екеуін де біріктіреді (қатаң, жария келісімшарттар үшін ыңғайлы).
NONE: тексерусіз - тек құмсалғыштар үшін.

Ұсынымдар:

Events: көбінесе BACKWARD (продюсер payload қосымша кеңейтеді).
Ашық API: FULL немесе BACKWARD + клиенттерге қатаң толерант reader.
Ішкі прототиптер: уақытша NONE, бірақ trunk емес.

Қауіпсіз (аддитивті) vs. қауіпті өзгерістер

Аддитивті (ОК):

Міндетті емес өрісті/түрді қосу.
Жаңа мәндермен enum кеңейту (tolerant reader кезінде).
Баламалы проекция/оқиғаны қосу ('.enriched').
Шектеулердің әлсіреуі ('minLength', 'maximum' ↑, бірақ ↓ емес).

Қауіпті (сындырады):

Өрістерді жою/қайта атау немесе олардың түрін/міндеттілігін өзгерту.
Ағындардағы мәртебе/кодек/тәртіп семантикасын өзгерту.
Protobuf-тегтерді қайта пайдалану.
Оқиғаларда партиялану кілтін ауыстыру.

Тізілімді ұйымдастыру

Нейминг және адрестеу

Топтар/кеңістіктер: 'payments', 'kyc', 'audit'.
'payment. authorized. v1` (events), `payments. v1. CaptureRequest` (gRPC), `orders. v1. Order` (JSON Schema).
Атаудағы мажор, схеманың/нұсқасындағы метадеректер.

Метадеректер

'owner' (команда), 'domain', 'slas' (SLO/SLA), 'security. tier` (PII/PCI), `retention`, `compatibility_mode`, `sunset`, `changelog`.

Тіршілік циклін басқару

Draft → Review → Approved → Released → Deprecated → Sunset.
Автоматты валидаторлар/линтерлер, қолмен жасалатын design-review (API Guild), release notes.

CI/CD біріктіру

1. Pre-commit: жергілікті линтерлер (Spectral/Buf/Euro tools).
2. PR-пайплайн: schema-diff → тексеру compatibility mode; breaking бұғаттаймыз.
3. Artifact publish: келісілген схеманы тізілімге қосу + SDK/модельдер генерациясы.
4. Runtime-guard (қосымша): шлюз/продюсер өзекті схемаға қарсы payload салыстырады.

PR қадамдарының үлгісі:

`openapi-diff --fail-on-breaking`
`buf breaking --against
`
`avro-compat --mode BACKWARD`
golden samples генерациясы және CDC-тесттерін өткізу.

Схемалардың эволюциясы: практикалар

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
Кері пирамида моделі: ядро тұрақты, байыту - жанында және опциондық.
major үшін dual-emit/dual-write: параллель түрде 'v1' және 'v2' деп жариялаймыз.
Sunset жоспары: күндер, пайдалану, ескертулер, адаптерлер.
Толерант reader: клиенттер белгісіз өрістерді елемейді және жаңа enum-ды дұрыс өңдейді.

Схемалар мен тексерулердің үлгілері

JSON Schema (үзік, аддитивті өріс)

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
}

💡 Қосымша ретінде 'risk _ score' қосылды → BACKWARD үйлесімді.

Euro (үйлесімділік үшін 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 (тегтерді қайта пайдаланбаңыз)

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

Оқиғалар тіркелімі және партиялану

Оқиғаларды атау: 'domain. action. v{major}` (`payment. captured. v1`).
Партияландыру кілті - келісімшарттың бөлігі ('payment _ id', 'user _ id').
Core vs Enriched: '.v1' (ядро) және '.enriched. v1 '(егжей- тегжейі).
Тізілімдегі үйлесімділік: тақырып/үлгі деңгейіндегі режимдер; CI сыйыспайтын өзгерістерден бас тартады.

Көші-қонды басқару

Expand → Migrate → Contract (REST/gRPC):

1. өрістерді/кестелерді қосу; 2) жаңа жолдарды жазуды/оқуды бастау; 3) sunset кейін ескісін жою.

Dual-emit (Events): параллель 'v1 '/' v2', консьюмерлер/проекциялар көші-қоны, содан кейін 'v1' алу.
Replay: логтан жаңа сұлбаға проекцияларды қайта жинау (тек сыйысымдылық және миграторлар кезінде).
Адаптерлер: гейтвей/прокси, аудару 'v1, v2' күрделі клиенттер үшін.

Қауіпсіздік және комплаенс

'x-pii: true', 'x-sensitivity: high' схемасындағы белгілер PII/PCI.
Кіру саясаты: схемаларды кім жариялай/өзгерте алады (RBAC), релиздерге қол қоя алады.
Криптография: схемалар нұсқаларының қолы, өзгермейтін аудит журналдары (WORM).
Ұмытылу құқығы: шифрлауды/крипто-өшіруді талап ететін өрістерді көрсетіңіз; тізімдегі guidance.

Бақылау және аудит

Дашбордтар: өзгерістер саны, түрлері (minor/major), қабылданбаған PR үлесі, нұсқаларды пайдалану.
Аудит-трейлер: схеманы кім өзгертті, PR/ADR сілтемелері, байланысты релизі.
Runtime-метриктер: валидациядан өтпеген хабарлардың пайызы; үйлесімділік оқиғалары.

Құралдар (үлгі стек)

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.
Тізілімдер/каталогтар: Artifact Registry, Git-based registry, Backstage Catalog, custom UI.
Құжаттама: Redocly/Stoplight, Swagger-UI, GraphiQL.

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

Swagger-wash: схема сервистің шынайылығын көрсетпейді (немесе керісінше).
Ажыратылған үйлесімділік тексерісі: «шұғыл болу керек» → өнім сынады.
Protobuf тегтерін қайта пайдалану: деректердің тыныш бүлінуі.
Барлығы үшін бірыңғай сыйысымдылық режимі: әртүрлі домендер әртүрлі режимдерді талап етеді.
Шикі CDC көпшілік схемалары ретінде: БД-модельдердің сыртқа шығып кетуі, эволюцияның мүмкін еместігі.

Енгізу парағы

Артефакттар пішімі және домендер бойынша compatibility mode анықталған.
CI-де линтерлер мен schema-diff орнатылған, PR breaking кезінде блокталады.
Клиенттерде tolerant reader қосылған; 'additionalProperties = true' (орынды).
Мажорлық өзгерістер RFC/ADR арқылы өтеді, sunset-жоспар және dual-emit/dual-write бар.
Схемалар PII/PCI және қол жеткізу деңгейлерімен белгіленген; аудит енгізілген.
Үйлесімділік нұсқаларын пайдалану және бас тарту бойынша дашбордтар.
Тізілімдегі SDK/модельдерінің генерациясы - пайплайнның бір бөлігі.
Құжаттама және алтын белгілер автоматты түрде жаңартылды.

FAQ

Тізілімсіз схемаларды Git бағдарламасында сақтауға бола ма?
Иә, бірақ тізілім үйлесімділік, іздеу, метадеректер, орталықтандырылған саясат және «on-the-fly» валидациясын қосады. Ең жақсы нұсқа - storage + UI/үстіңгі саясат ретінде Git.

Сыйысымдылық режимін қалай таңдауға болады?
Өзгерістердің бағытын қараңыз: егер продюсер payload - BACKWARD кеңейтетін болса. Көпшілік API/SDK үшін - FULL. Жылдам прототиптер үшін - уақытша NONE (trunk емес).

Қажет болған жағдайда не істеу керек?
v2 дайындаймыз: dual-emit/dual-run, sunset-даталар, адаптерлер, телеметрия пайдалану, көші-қон гайдтары.

Payload бағдарламасын рантаймда валидациялау керек пе?
Сындарлы домендер үшін - иә: бұл «қоқыс» хабарламаларын болдырмайды және диагностиканы жеделдетеді.

Жиынтық

Схемалар тізілімі деректердің эволюциясын қауіпті импровизациядан басқарылатын процеске айналдырады: үйлесімділіктің бірыңғай ережелері, автоматты тексерулер, түсінікті нұсқалар және ашық тарих. Оған additive-first, tolerant reader, dual-emit және sunset тәртібін қосыңыз - және сіздің келісімшарттар тез дамиды, сынусыз және түнгі оқиғалар жоқ.