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

Эмне үчүн схемалар реестри керек

• Болжолдуу эволюция: шайкештик эрежелери жана автоматтык текшерүү "сынык".
• Кайталануучулук жана ачык-айкындуулук: версиялардын тарыхы, ким/качан/эмне үчүн өзгөргөн.
• Стандартташтыруу: бирдиктүү аталыштар, ката форматтары, трек талаалары, PII-белгилер.
• CI/CD менен интеграция: өндүрүүгө чейин breaking-өзгөрүүлөрдү бөгөттөө.

Реестр өзгөрүүлөрдү тез жана коопсуз кылып, Protocol-биринчи жана келишим шайкештигин байланыштырат.

Форматтар жана колдонуу чөйрөлөрү

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

Шайкештик режимдери

BACKWARD: жаңы схемалар эски маалыматтарды/билдирүүлөрдү окуп. PayLoad кошумча кеңейтет продюсер үчүн ылайыктуу.
FORWARD: эски керектөөчүлөр туура жаңы маалыматтарды окуп (толеранттуу reader талап кылат).
FULL: экөөнү тең бириктирет (катуу, ачык келишимдер үчүн ыңгайлуу).
NONE: текшерүү жок - гана кум кутучалар үчүн.

• Events: көбүнчө BACKWARD (продюсер кошумча төлөмдөрдү кеңейтет).
• Коомдук API: ТОЛУК же BACKWARD + кардарлар боюнча катуу толеранттуу reader.
• Ички прототиптери: убактылуу NONE, бирок trunk эмес.

Коопсуз (кошумча) ж.б. коркунучтуу өзгөрүүлөр

Аддитивдик

Кошумча талаа/түрүн кошуу.
Жаңы баалуулуктар менен enum кеңейтүү (толеранттуу 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.
Automatic валидаторлор/линтерлер, кол менен design-review (API Guild), release notes.

CI/CD интеграциясы

1. Pre-commit: Local Linters (Spectral/Buf/Euro tools).
2. PR-paypline: schema-diff → текшерүү compatibility mode; breaking бөгөт коюу.
3. Artifact publish: реестрине макулдашуу схемасы + SDK/моделдерин түзүү.
4. Runtime-guard (кошумча): шлюз/продюсер учурдагы схемага каршы төлөмдү тастыктайт.

• `openapi-diff --fail-on-breaking`
• `buf breaking --against
  `
• `avro-compat --mode BACKWARD`
• алтын үлгүлөрүн түзүү жана CDC сыноолордун өтүү.

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

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

Схемалардын жана текшерүүлөрдүн мисалдары

JSON схемасы (фрагмент, кошумча талаа)

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
}

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

Окуялардын реестри жана партиялаштыруу

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

Миграцияны башкаруу

1. талааларды/таблицаларды кошуу; 2) жаңы талааларды жазуу/окуу башталат; 3) sunset кийин эски алып салуу.

• Dual-emit (Events): параллелдүү 'v1 '/' v2', консумерлердин/проекциялардын миграциясы, андан кийин 'v1' алып салуу.
• Replay: жаңы схемага логунун проекцияларды кайра чогултуу (шайкештик жана миграторлор менен гана).
• Adapters: Gateway/Proxy, татаал кардарлар үчүн котормо 'v1, v2'.

Коопсуздук жана комплаенс

схемасында PII/PCI белгилер: 'x-pii: true', 'x-sensitivity: high'.
Кирүү саясаты: Схемаларды (RBAC) ким жарыялай алат/өзгөртө алат, релиздерге кол коет.
Криптография: схемалардын версияларынын кол тамгасы, өзгөрүлбөгөн аудит журналдары (WORM).
Unut укугу: коддоо/крипто-өчүрүү талап талааларды көрсөтүү; реестринде guidance.

Байкоо жана аудит

Dashbord: өзгөрүүлөрдүн саны, түрлөрү (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 коомдук схемалар катары: DD моделдин сыртка чыгышы, эволюциянын мүмкүн эместиги.

Киргизүүнүн чек-тизмеси

• Домендер боюнча артефакттар жана compatibility режиминин форматы аныкталган.
• CIде linters жана schema-diff орнотулган, PR breaking учурунда бөгөттөлгөн.
• Кардарлар үчүн толерант reader кирет; 'additionalProperties = true' (ылайыктуу жерде).
• Негизги өзгөрүүлөр RFC/ADR аркылуу өтөт, sunset-план жана dual-emit/dual-write бар.
• Схемалар PII/PCI жана жеткиликтүүлүк менен белгиленет; аудит киргизилген.
• Dashboard нускаларын колдонуу жана шайкештикти аткарбоо.
• Реестрдеги SDK/моделдерин түзүү - пайплайн бир бөлүгү.
• Документтер жана алтын үлгүлөрү автоматтык түрдө жаңыртылган.

FAQ

Реестрсиз болушу мүмкүнбү - схемаларды Git 'те сактоо?
Ооба, бирок реестри API шайкештикти, издөө, метадеректер, борборлоштурулган саясат жана "on-the-fly" валидациясын кошот. Мыкты параметр - storage + UI/саясат боюнча Git.

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

Керек болсо эмне кылуу керек?
v2 даярдоо: dual-emit/dual-run, sunset-даталар, адаптерлер, телеметрия пайдалануу, миграциялык гайддар.

Мен рантайм боюнча payload validation керекпи?
Критикалык домендер үчүн - ооба: бул "таштанды" билдирүүлөрдү алдын алат жана диагностиканы тездетет.

Жыйынтык

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