Şema kaydı ve veri gelişimi

Neden bir şema kayıt defterine ihtiyacım var

Şema Kayıt Defteri, aşağıdakileri sağlayan veri sözleşmeleri (API'ler, olaylar, konular, mesajlar, mağazalar) için merkezi bir doğruluk kaynağıdır:

Öngörülebilir evrim: uyumluluk kuralları ve otomatik kırılma kontrolü.
Tekrarlanabilirlik ve şeffaflık: sürümlerin geçmişi, kim/ne zaman/neden değişti.
Standardizasyon: tek tip isimler, hata biçimleri, izleme alanları, PII etiketleri.
CI/CD ile entegrasyon: Üretimden önce kırılma değişikliklerini engelleme.

Kayıt defteri, Protokol-ilk ve sözleşme uyumluluğunu birbirine bağlayarak değişiklikleri hızlı ve güvenli hale getirir.

Formatlar ve uygulamalar

JSON Şeması: REST/HTTP yükleri, belgeler, yapılandırmalar.
Avro: olay otobüsleri (Kafka/Pulsar), alan kimliği ile kompakt/evrim.
Protobuf: gRPC/RPC, ikili verimli, katı etiketler.
GraphQL SDL: type and directive schema, evolution via '@ depressed'.
Bir eser olarak SQL DDL: kararlaştırılan görüşleri (örneğin, harici vitrinler) - dikkatli bir şekilde düzeltiyoruz.

💡 Tek bir kayıt defteri aynı anda birden fazla eser türünü depolayabilir, ancak ayrı uyumluluk politikalarıyla.

Uyumluluk modları

BACKWARD: Yeni şemalar eski verileri/mesajları okur. Ek olarak yükü uzatan bir üretici için uygundur.
FORWARD: Eski tüketiciler yeni verileri doğru okur (hoşgörülü bir okuyucu gerektirir).
TAM: her ikisini de birleştirir (kamu sözleşmeleri için daha katı, daha uygun).
YOK: kontrol yok - sadece kum havuzları için.

Öneriler:

Olaylar: Daha sık GERI (üretici isteğe bağlı yükü uzatır).
Genel API'ler: İstemcilerde TAM veya GERIYE DÖNÜK + katı toleranslı okuyucu.
Dahili prototipler: geçici olarak YOK, ancak gövde üzerinde değil.

Güvenli (katkı) ve tehlikeli değişiklikler

Katkı maddesi (Tamam):

İsteğe bağlı bir alan/tür ekleyin.
Yeni değerlerle Enum uzantısı (toleranslı okuyucu ile).
Alternatif projeksiyon/olay ('.enriched') ekleyin.
Kısıtlamaları hafifletme ('MinLength', 'maximum' ↑, ancak ↓ değil).

Tehlikeli (mola):

Alanları silin/yeniden adlandırın veya türlerini/zorunlu olarak değiştirin.
Dizilerdeki status/codec/order anlamlarının değiştirilmesi.
Protobuf etiketlerinin yeniden kullanımı.
Olaylardaki bölümleme anahtarını değiştirme.

Kayıt organizasyonu

Adlandırma ve adresleme

Gruplar/alanlar: 'ödemeler', 'kyc', 'denetim'.
İsimler: 'ödeme. yetkilendirildi. v1 '(olaylar)', ödemeler. v1. CaptureRequest '(gRPC)', emirler. v1. Sipariş '(JSON Şeması).
Büyük adı, meta/şema sürümünde küçükler.

Meta veriler

'owner' (komut), 'domain', 'slas' (SLO/SLA), 'security. Tier '(PII/PCI),' retention ',' compatibility _ mode ',' sunset ',' changelog '.

Yaşam Döngüsü Yönetimi

Taslak- İnceleme - Onaylandı - Yayınlandı - Kullanımdan Kaldırıldı - Sunset.
Otomatik doğrulayıcılar/doğrulayıcılar, manuel tasarım-inceleme (API Guild), sürüm notları.

CI/CD'ye entegrasyon

1. Ön taahhüt: yerel linterler (Spektral/Buf/Avro araçları).
2. PR-pipeline: şema-diff> uyumluluk modu kontrolü; bloklama kırma.
3. Artifact yayınlama: tutarlı şemayı kayıt defterine itin + SDK/modeller oluşturun.
4. Runtime-guard (isteğe bağlı): Gateway/producer geçerli şemaya karşı yükü doğrular.

PR'daki adımlara örnek:

'openapi-diff --fail-on-breaking'
'buf kırma --against
'
'avro-compat --mode BACKTARD'
Altın numuneler üretmek ve CDC testleri yapmak.

Şemaların evrimi: uygulamalar

İlk katkı maddesi: новые поля - 'isteğe bağlı/geçersiz' (JSON), 'isteğe bağlı' (proto3), varsayılan в Avro.
Ters piramit modeli: çekirdek stabildir, zenginleştirme yakın ve isteğe bağlıdır.
Dual-emit/dual-write for major: 'v1've' v2'yi paralel olarak yayınlıyoruz.
Günbatımı planı: tarihler, kullanımlar, uyarılar, adaptörler.
Toleranslı okuyucu: istemciler bilinmeyen alanları yoksayar ve yeni enumu doğru şekilde işler.

Plan ve kontrol örnekleri

JSON Şeması (parça, katkı alanı)

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
}

💡 Eklendi 'risk _ score' as optional> BACKWARD uyumludur.

Avro (uyumluluk için öntanımlı)

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 (etiketleri tekrar kullanmayın)

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

Olay kaydı ve bölümleme

Olayları adlandırma: 'domain. eylem. v {major} '(' ödeme. yakalandı. v1 ').
Bölümleme anahtarı sözleşmenin bir parçasıdır ('payment _ id', 'user _ id').
Core vs Zenginleştirilmiş: '.v1' (çekirdek) ve '.enriched. v1 '(ayrıntılar).
Kayıt defteri uyumluluğu: tema/tip seviyesindeki modlar; CI uyumsuz değişiklikleri reddediyor.

Geçiş Yönetimi

Genişlet - Geçir - Sözleşme (REST/gRPC):

1. Alanları/tabloları ekleyin 2) yeni alanları yazmaya/okumaya başlayın; 3) gün batımından sonra eski silin.

Çift yayma (Olaylar): 'v1'/' v2'ye paralel, tüketici/projeksiyon geçişi, ardından' v1'in kaldırılması.
Yeniden oynatma: Projeksiyonları günlükten yeni bir diyagrama yeniden birleştirme (yalnızca uyumluluk ve göç edenlerle).
Adaptörler: Karmaşık istemciler için 'v1↔v2' çeviren ağ geçitleri/proxy'ler.

Güvenlik ve uyumluluk

Diyagramdaki PII/PCI etiketleri: 'x-pii: true', 'x-sensitivity: high'.
Erişim ilkeleri: Kimler şemaları (RBAC) yayınlayabilir/değiştirebilir, sürümleri imzalayabilir.
Kriptografi: şema sürümlerinin imzası, değişmez denetim günlükleri (WORM).
Unutulma hakkı: Şifreleme/kripto silme gerektiren alanları belirtin; kayıt defterinde rehberlik.

Gözlemlenebilirlik ve denetim

Panolar: değişiklik sayısı, türleri (küçük/büyük), reddedilen PR'ların payı, sürüm kullanımı.
Denetim izi: Şemayı kim değiştirdi, PR/ADR'ye bağlantılar, ilgili sürüm.
Çalışma zamanı metrikleri: doğrulama başarısız olan iletilerin yüzdesi; Uyumluluk olayları.

Araçlar (örnek yığın)

OpenAPI/JSON Şeması: Spektral, OpenAPI Diff, Şematez.
Protobuf/gRPC: Buf, buf kırma, linters.
Avro/Olaylar: Confluent/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: GraphQL Inspector, GraphQL Codegen.
Kayıtlar/kataloglar: Artifact Registry, Git tabanlı kayıt defteri, Backstage Catalog, özel UI.
Belgeler: Redocly/Stoplight, Swagger-UI, GraphiQL.

Anti-desenler

Swagger-wash: şema hizmetin gerçekliğini yansıtmaz (veya tam tersi).
Devre dışı uyumluluk kontrolü: "Acil" - ürün kırılır.
Protobuf etiketlerini yeniden kullanma: sessiz veri bozulması.
Tek uyumluluk modu'her şey için ": farklı alanlar farklı modlar gerektirir.
Halka açık programlar olarak ham CDC'ler: DB modelini sızdırmak, evrimin imkansızlığı.

Uygulama kontrol listesi

Tanımlı artefakt formatı ve etki alanına göre uyumluluk modu.
Linters ve şema-diff CI yapılandırılmış, PR kırarken engellenir.
Müşterilerin hoşgörülü okuyucusu için etkinleştirildi; 'additionalProperties = true' (varsa).
Büyük değişiklikler RFC/ADR'den geçer, bir gün batımı planı ve çift yayma/çift yazma vardır.
Devreler PII/PCI ve erişim seviyeleri ile işaretlenmiştir; denetim etkinleştirildi.
Sürüm kullanımı ve uyumluluk hataları panoları.
Kayıt defterinden SDK/model üretmek boru hattının bir parçasıdır.
Belgeler ve altın numuneler otomatik olarak güncellendi.

SSS

Git'te şemaları saklamak için bir kayıt defteri olmadan mümkün mü?
Evet, ancak kayıt defteri uyumluluk API'leri, arama, meta veriler, merkezi ilke ve anında doğrulama ekler. En iyi seçenek depolama olarak Git + UI/politikalar üstte.

Uyumluluk modunu nasıl seçerim?
Değişimin yönüne bakın: eğer üretici yükü genişletirse - GERIYE DOĞRU. Genel API/SDK için - FULL. Hızlı prototipler için - geçici olarak YOK (gövde üzerinde değil).

Gerekirse kırma ne yapmalı?
Hazırlama v2: çift yayma/çift çalıştırma, gün batımı tarihleri, adaptörler, kullanım telemetrisi, geçiş kılavuzları.

Çalışma zamanında yükü doğrulamam gerekiyor mu?
Kritik etki alanları için evet: bu, gereksiz mesajları önler ve tanılamayı hızlandırır.

Sonuç

Şema kaydı, verilerin evrimini riskli doğaçlamadan yönetilebilir bir sürece dönüştürür: tek tip birlikte çalışabilirlik kuralları, otomatik doğrulamalar, anlaşılır sürümler ve şeffaf bir geçmiş. Buna ilk katkı maddesi, hoşgörülü okuyucu, çift yayma ve gün batımı disiplinini ekleyin - sözleşmeleriniz arıza ve gece olayları olmadan hızlı bir şekilde gelişecektir.