სქემების რეესტრი და მონაცემთა ევოლუცია

რატომ გვჭირდება სქემების რეესტრი

• პროგნოზირებადი ევოლუცია: თავსებადობის წესები და „ხარვეზების“ ავტომატური შემოწმება.
• განმეორება და გამჭვირვალობა: ვერსიის ისტორია, ვინ/როდის/რატომ შეიცვალა.
• სტანდარტიზაცია: ერთიანი სახელები, შეცდომის ფორმატები, ტრეკერის ველები, PII ეტიკეტები.
• ინტეგრაცია CI/CD- სთან: breaking ცვლილებების ბლოკირება წარმოებამდე.

რეესტრი აკავშირებს Protocol-first- ს და ხელშეკრულების თავსებადობას, რაც ცვლილებებს სწრაფად და უსაფრთხოდ ხდის.

ფორმატები და გამოყენების სფეროები

JSON Schema: REST/HTTP დატვირთვა, დოკუმენტები, კონფიგურაცია.
Avro: ღონისძიების საბურავები (Kafka/Pulsar), კომპაქტური/ევოლუცია ველების ID საშუალებით.
Protobuf: gRPC/RPC, ორობითი ეფექტური, მკაცრი ჭდეები.
GraphQL SDL: ტიპებისა და დირექტივების სქემა, ევოლუცია '@ deprecated' საშუალებით.
SQL DDL, როგორც არტეფაქტი: ჩაწერეთ შეთანხმებული წარმოდგენები (მაგალითად, გარე ფანჯრები) - სიფრთხილით.

თავსებადობის რეჟიმები

BACKWARD: ახალი სქემები კითხულობს ძველ მონაცემებს/შეტყობინებებს. შესაფერისია მწარმოებლისთვის, რომელიც payload დანამატს აფართოებს.
FORWARD: ძველი მომხმარებლები სწორად კითხულობენ ახალ მონაცემებს (მოითხოვს tolerant reader).
FULL: აერთიანებს ორივე (უფრო მკაცრი, უფრო მოსახერხებელი საზოგადოებრივი კონტრაქტებისთვის).
NONE: შემოწმების გარეშე - მხოლოდ ქვიშის ყუთებისთვის.

• Events: უფრო ხშირად BACKWARD (პროდიუსერი სურვილისამებრ აფართოებს payload).
• საზოგადოებრივი API: FULL ან BACKWARD + მკაცრი tolerant reader კლიენტებზე.
• შიდა პროტოტიპები: დროებით NONE, მაგრამ არა ტრუნკზე.

უსაფრთხო (დანამატი) 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), 'უსაფრთხოება. tier` (PII/PCI), `retention`, `compatibility_mode`, `sunset`, `changelog`.

სასიცოცხლო ციკლის მართვა

Draft → Review → Approved → Released → Deprecated → Sunset.
ავტომატური მიმღები/ლინტერი, სახელმძღვანელო მიმოხილვა (API Guild), release notes.

ინტეგრაცია CI/CD- ში

1. Pre commit: ადგილობრივი საბრძოლო მასალები (Spectral/Buf/Avro tools).
2. PR pipline: schema-diff - კომპოზიციური სისტემის შემოწმება; დაბლოკეთ breaking.
3. Artifact publish: შეთანხმებული სქემა რეესტრში + SDK/მოდელების წარმოებაში.
4. Runtime guard (სურვილისამებრ): კარიბჭე/პროდიუსერი ლიდერობს payload მიმდინარე სქემის წინააღმდეგ.

• `openapi-diff --fail-on-breaking`
• `buf breaking --against
  `
• `avro-compat --mode BACKWARD`
• Golden samples და CDC ტესტების პროგონი.

სქემების ევოლუცია: პრაქტიკა

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
საპირისპირო პირამიდის მოდელი: ბირთვი სტაბილურია, გამდიდრება - იქვე და სურვილისამებრ.
ორმაგი-ემიტი/ორმაგი-write major- ისთვის: პარალელურად გამოაქვეყნეთ 'v1' და 'v2'.
Sunset გეგმა: თარიღები, გამოყენება, გაფრთხილებები, გადამყვანები.
Tolerant reader: მომხმარებლები უგულებელყოფენ უცნობ სფეროებს და სწორად ამუშავებენ ახალ ენებს.

სქემების და შემოწმების მაგალითები

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
}

Avro (თავსებადობა)

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 უარს ამბობს შეუთავსებელ ცვლილებებზე.

მიგრაციის მენეჯმენტი

1. დაამატეთ ველები/ცხრილი; 2) დაიწყეთ ახალი ველების წერა/კითხვა; 3) ძველი ამოღება სუნსეტის შემდეგ.

• Dual emit (Events): პარალელურად 'v1 '/' v2', კონსიუმერების/პროექციების მიგრაცია, შემდეგ ამოღება 'v1'.
• Replay: ლოგოდან პროექციების შეცვლა ახალ სქემაზე (მხოლოდ თავსებადობისა და მიგრანტების დროს).
• გადამყვანები: გეითვეი/მარიონეტები, რომლებიც თარგმნიან 'v1-v2' რთული მომხმარებლებისთვის.

უსაფრთხოება და შესაბამისობა

PII/PCI ეტიკეტები სქემაში: 'x-pii: ნამდვილი', 'x-sensitivity: high'.
დაშვების პოლიტიკოსები: ვისაც შეუძლია გამოაქვეყნოს/შეცვალოს სქემები (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 რეგისტრი, Backstage Catalog, custom UI.
დოკუმენტაცია: Redocly/Stoplight, Swagger-UI, GraphiQL.

ანტიპატერები

Swagger-wash: სქემა არ ასახავს მომსახურების რეალობას (ან პირიქით).
თავსებადობის გამორთული შემოწმება: „საჭიროა სასწრაფოდ“ - გამონაყარი იშლება.
Protobuf ტეგების ხელახალი გამოყენება: მონაცემების მშვიდი დაზიანება.
ერთჯერადი თავსებადობის რეჟიმი „ყველაფრისთვის“: სხვადასხვა დომენები მოითხოვს სხვადასხვა რეჟიმებს.
ნედლეული CDC, როგორც საჯარო სქემები: BD მოდელის გაჟონვა, ევოლუციის შეუძლებლობა.

განხორციელების შემოწმების სია

• განისაზღვრება დომენების არტეფაქტებისა და კომპოზიციური სისტემის ფორმატი.
• Linters და schema-diff CI- ში, PR იბლოკება breaking.
• tolerant reader შედის მომხმარებლებში; 'additionalProperties = true' (სადაც შესაფერისია).
• მთავარი ცვლილებები გადის RFC/ADR, არის sunset გეგმა და ორმაგი ემიტი/ორმაგი-write.
• სქემები აღინიშნება PII/PCI და დაშვების დონით; აუდიტი ჩართულია.
• დაშბორდები ვერსიების გამოყენებისა და თავსებადობის უარის თქმის შესახებ.
• რეესტრიდან SDK/მოდელების გამომუშავება ნაწილაკების ნაწილია.
• დოკუმენტაცია და golden samples ავტომატურად განახლებულია.

FAQ

შესაძლებელია რეესტრის გარეშე - შეინახოთ სქემები Git- ში?
დიახ, მაგრამ რეესტრს ემატება თავსებადობა, ძებნა, მეტამონაცემები, ცენტრალიზებული პოლიტიკა და „ფრენის“ მოქმედება. საუკეთესო ვარიანტია Git, როგორც სცენა + UI/პოლიტიკა თავზე.

როგორ ავირჩიოთ თავსებადობის რეჟიმი?
შეხედეთ ცვლილებების მიმართულებას: თუ პროდიუსერი აფართოებს payload - BACKWARD. საზოგადოებრივი API/SDK - FULL. სწრაფი პროტოტიპებისთვის - დროებით NONE (არა ტრუნკზე).

რა უნდა გავაკეთოთ საჭიროების შემთხვევაში?
ჩვენ ვამზადებთ v2: dul-emit/dul-run, sunset თარიღები, გადამყვანები, ტელემეტრია, მიგრაციის ჰაიდები.

საჭიროა თუ არა payload- ის ხელმძღვანელობა ranthime- ში?
კრიტიკული დომენებისთვის - დიახ: ეს ხელს უშლის „ნაგვის“ შეტყობინებებს და აჩქარებს დიაგნოზს.

შედეგი

სქემების რეესტრი მონაცემების ევოლუციას სარისკო იმპროვიზაციიდან აქცევს კონტროლირებად პროცესად: თავსებადობის ერთიანი წესები, ავტომატური შემოწმება, გასაგები ვერსიები და გამჭვირვალე ისტორია. დაამატეთ დისციპლინა additive-first, tolerant reader, dul-emit და sunset - და თქვენი კონტრაქტები სწრაფად განვითარდება, ხარვეზებისა და ღამის ინციდენტების გარეშე.