Shemalaryň sanawy we maglumatlaryň ewolýusiýasy

Näme üçin shemalaryň sanawy gerek?

Shemalaryň sanawy maglumatlaryň (API, wakalar, akymlar, habarlar, ammar) şertnamalary üçin merkezleşdirilen hakykat çeşmesidir, ol:

Öňünden aýdyp boljak ewolýusiýa: laýyklyk düzgünleri we "döwük" awtomatiki barlag.
Gaýtalanma we aç-açanlyk: wersiýalaryň taryhy, kim/haçan/näme üçin üýtgedildi.
Standartlaşdyrma: birmeňzeş atlar, ýalňyşlyk formatlary, ýol meýdançalary, PII bellikleri.
CI/CD bilen integrasiýa: öndürilýänçä breaking-üýtgeşmeleri bloklamak.

Reýestr Protocol-first we şertnama laýyklygyny baglanyşdyrýar, üýtgeşmeleri çalt we ygtybarly edýär.

Formatlar we ulanylýan ýerler

JSON Shema: REST/HTTP peýdaly ýükler, resminamalar, konfigurasiýalar.
Euro: Waka tekerleri (Kafka/Pulsar), compact/meýdan ID arkaly ewolýusiýa.
Protobuf: gRPC/RPC, ikilik täsirli, berk bellikler.
GraphQL SDL: "@deprecated" arkaly ewolýusiýa.
SQL DDL artefakt hökmünde: ylalaşylan görkezmeleri belleýäris (mysal üçin, daşarky penjireler) - seresaplylyk bilen.

💡 Bir reýestr bir wagtyň özünde artefaktlaryň birnäçe görnüşini saklap biler, ýöne aýry-aýry laýyklyk syýasatlary bilen.

Gabat geliş usullary

BACKWARD: Täze shemalar köne maglumatlary/habarlary okaýar. PayLoad-y goşmaça giňeldýän prodýuser üçin amatly.
FORWARD: Köne sarp edijiler täze maglumatlary dogry okaýarlar (tolerant reader talap edýär).
FULL: ikisini hem birleşdirýär (has berk, köpçülikleýin şertnamalar üçin has amatly).
NONE: barlagsyz - diňe gum gutulary üçin.

Teklipler:

Wakalar: köplenç BACKWARD (prodýuser tölegleri goşmaça giňeldýär).
Açyk API: FULL ýa-da BACKWARD + müşderilerde berk tolerant reader.
Içerki prototipler: NONE wagtlaýyn, ýöne trunk däl.

Howpsuz (goşmaça) vs. howply üýtgeşmeler

Goşmaça (OK):

Goşmaça meýdan/görnüş goşmak.
Täze bahalar bilen enum giňeltmek (tolerant reader bilen).
Alternatiw proýeksiýany/wakany goşmak ('.enriched').
Çäklendirmeleri ýeňilleşdirmek ('minLength', 'maximum' ↑, ýöne ↓ däl).

Howply (döwmek):

Meýdanlary aýyrmak/adyny üýtgetmek ýa-da olaryň görnüşini/borçlylygyny üýtgetmek.
Akymlarda statuslaryň/kodekleriň/tertibiň semantikasyny üýtgetmek.
Protobuf-taglary gaýtadan ulanmak.
Wakalarda partiýa açaryny üýtgetmek.

Reýestri guramak

Neýming we adres

Toparlar/giňişlikler: 'payments', 'kyc', 'audit'.
Adlar: 'payment. authorized. v1` (events), `payments. v1. CaptureRequest` (gRPC), `orders. v1. Order` (JSON Schema).
Mazor adynda, minorlar - meta-maglumatlarda/shemanyň wersiýasynda.

Metadata

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

Durmuş siklini dolandyrmak

Draft → Review → Approved → Released → Deprecated → Sunset.
Awtomatiki tassyklaýjylar/linterler, elde ýasalan design-review (API Guild), release notes.

CI/CD integrasiýasy

1. Pre-commit: lokal linterler (Spectral/Buf/Euro tools).
2. PR-paypline: schema-diff → compatibility mode barlagy; breaking-i bloklaýarys.
3. Artifact publish: SDK/modelleriň sanawynda ylalaşylan shemany düzmek.
4. Runtime-guard (goşmaça): Şlýuz/prodýuser häzirki shema garşy tölegleri tassyklaýar.

PR ädimleriniň mysaly:

`openapi-diff --fail-on-breaking`
`buf breaking --against
`
`avro-compat --mode BACKWARD`
altyn samples öndürmek we CDC synaglaryny geçirmek.

Shemalaryň ewolýusiýasy: amallar

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
Ters piramidanyň modeli: ýadro durnukly, baýlaşdyrmak - ýakyn we opsiýa.
major üçin dual-emit/dual-write: paralel ýagdaýda 'v1' we 'v2' -ni çap edýäris.
Sunset-plan: seneler, ulanmak, duýduryşlar, adapterler.
Tolerant reader: Müşderiler näbelli ýerleri äsgermezlik edýärler we täze enumlary dogry dolandyrýarlar.

Shemalaryň we barlaglaryň mysallary

JSON Shema (bölek, goşmaça meýdan)

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
}

💡 Goşmaça hökmünde 'risk _ score' goşuldy → BACKWARD gabat gelýär.

Euro (gabat gelmek üçin 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 (bellikleri ulanmaň)

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

Wakalary hasaba almak we partiýa ýerleşdirmek

Wakalaryň ady: 'domain. action. v{major}` (`payment. captured. v1`).
Partiýanyň açary - şertnamanyň bir bölegi ('payment _ id', 'user _ id').
Core vs Enriched: '.v1' (ýadro) we '.enriched. v1 '(jikme-jiklikler).
Reýestrdäki laýyklyk: tema/görnüş derejesindäki reimesimler; CI gabat gelmeýän üýtgetmeleri ret edýär.

Migrasiýa dolandyryşy

Expand → Migrate → Contract (REST/gRPC):

1. meýdan/tablisa goşmak; 2) täze meýdanlary ýazmaga/okamaga başlamak; 3) sunsetden soň köne aýyrmak.

Dual-emit (Events): paralel 'v1 '/' v2', konsumerleriň/proýeksiýalaryň göçmegi, soňra 'v1' -ni aýyrmak.
Replay: proýeksiýalary logdan täze shema gaýtadan ýygnamak (diňe gabat gelýän we migratorlarda).
Adapterler: çylşyrymly müşderiler üçin 'v1 v2' terjime edýän gatweý/proxy.

Howpsuzlyk we laýyklyk

PII/PCI şemasyndaky bellikler: 'x-pii: true', 'x-sensitivity: high'.
Giriş syýasaty: Kim shemalary çap edip/üýtgedip biler (RBAC), neşirlere gol çekip biler.
Kriptografiýa: shemalaryň wersiýalarynyň goly, üýtgemeýän audit žurnallary (WORM).
Ýatdan çykarmak hukugy: şifrlemegi/kripto-silmegi talap edýän meýdanlary görkeziň; sanawda guidance.

Gözegçilik we audit

Daşbordlar: üýtgeşmeleriň sany, görnüşleri (minor/major), ret edilen PR-leriň paýy, wersiýalary ulanmak.
Audit-trail: shemany kim üýtgetdi, PR/ADR baglanyşyklary, baglanyşykly goýberiş.
Runtime-metrikler: tassyklanmadyk habarlaryň göterimi; gabat gelmek hadysalary.

Gurallar (görelde)

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

Antipattern

Swagger-wash: shema hyzmatyň hakykatyny görkezmeýär (ýa-da tersine).
Utgaşyklyk barlagy öçürildi: "gyssagly gerek" → önüm döwülýär.
Protobuf belliklerini gaýtadan ulanmak: maglumatlaryň ýuwaşlyk bilen zaýalanmagy.
"Hemme zat üçin" ýeke-täk laýyklyk düzgüni: dürli domenler dürli re modeimleri talap edýär.
Çig CDC jemgyýetçilik shemalary hökmünde: DB modeliniň syzmagy, ewolýusiýanyň mümkin däldigi.

Giriş barlagy

Artefaktlaryň formaty we domenler boýunça compatibility mode kesgitlenildi.
CI-de linterler we schema-diff sazlandy, PR döwülende petiklenýär.
Müşderileriňizde tolerant reader açyldy; 'additionalProperties = true' (ýerlikli).
Esasy üýtgeşmeler RFC/ADR-den geçýär, sunset meýilnamasy we dual-emit/dual-write bar.
Shemalar PII/PCI we giriş derejeleri bilen bellendi; audit girizildi.
Wersiýalary ulanmak we gabat gelmezlik boýunça daşbordlar.
SDK/modelleri sanawdan döretmek - paýlaýjynyň bir bölegi.
Resminamalar we golden samples awtomatiki usulda täzelendi.

FAQ

Sanawsyz shemalary Git-de saklamak mümkinmi?
Hawa, ýöne reýestr API gabat gelmek, gözleg, meta-maglumatlar, merkezleşdirilen syýasat we "on-the-fly" tassyklamany goşýar. Iň oňat wariant - Git storage + UI/syýasatlar ýaly.

Laýyklyk tertibini nädip saýlamaly?
Üýtgeşmeleriň ugruna serediň: eger öndüriji payload - BACKWARD giňeldýän bolsa. Jemgyýetçilik API/SDK üçin - FULL. Çalt prototipler üçin - wagtlaýyn NONE (trunk däl).

Zerur bolsa näme etmeli?
v2 taýýarlaýarys: dual-emit/dual-run, sunset-seneler, adapterler, telemetriýa ulanmak, migrasiýa gaýdylary.

Tölegleri kärendede tassyklamalymy?
Möhüm domenler üçin - hawa: bu "zibil" habarlarynyň öňüni alýar we diagnostikany çaltlaşdyrýar.

Jemi

Shemalaryň sanawy maglumatlaryň ewolýusiýasyny töwekgelçilikli improwizasiýadan dolandyrylýan prosese öwürýär: bitewi laýyklyk düzgünleri, awtomatiki barlaglar, düşnükli wersiýalar we aç-açan taryh. Oňa additive-first, tolerant reader, dual-emit we sunset düzgünini goşuň - şertnamalaryňyz bökdençsiz we gijeki hadysalarsyz çalt öser.