Rejestr schematu i ewolucja danych

Dlaczego potrzebuję rejestru schematu

Rejestr schematu jest scentralizowanym źródłem prawdy dla umów o dane (API, zdarzenia, wątki, wiadomości, sklepy), który zapewnia:

Przewidywalna ewolucja: zasady kompatybilności i automatyczne sprawdzanie awarii.
Powtarzalność i przejrzystość: historia wersji, kto/kiedy/dlaczego zmienił.
Standaryzacja: jednolite nazwy, formaty błędów, pola śladowe, etykiety PII.
Integracja z CI/CD: blokowanie zmian przed produkcją.

Rejestr łączy Protokół-pierwszy i kompatybilność umowy, dzięki czemu zmiany są szybkie i bezpieczne.

Formaty i aplikacje

Schemat JSON: ładunki REST/HTTP, dokumenty, konfiguracje.
Avro: autobusy imprezowe (Kafka/Pulsar), kompaktowe/ewolucyjne poprzez identyfikator pola.
Protobuf: gRPC/RPC, wydajne binarne, ścisłe znaczniki.
GraphQL SDL: schemat typu i dyrektywy, ewolucja poprzez '@ deprecated'.
SQL DDL jako artefakt: naprawiamy uzgodnione widoki (na przykład zewnętrzne sklepy) - z ostrożnością.

💡 Pojedynczy rejestr może przechowywać wiele typów artefaktów naraz, ale z oddzielnymi zasadami kompatybilności.

Tryby kompatybilności

WSTECZ: Nowe schematy odczytują stare dane/wiadomości. Nadaje się do producenta, który dodatkowo rozszerza ładunek.
NAPRZÓD: starzy konsumenci prawidłowo odczytują nowe dane (wymaga tolerancyjnego czytnika).
FULL: łączy oba (bardziej rygorystyczne, wygodniejsze dla zamówień publicznych).
BRAK: brak kontroli - tylko dla piaskownic.

Zalecenia:

Wydarzenia: częściej BACKWARD (producent rozszerza ładunek opcjonalnie).
Publiczne interfejsy API: FULL lub BACKWARD + surowy tolerancyjny czytnik dla klientów.
Prototypy wewnętrzne: tymczasowo NIE, ale nie na bagażniku.

Bezpieczne (dodatek) vs niebezpieczne zmiany

Dodatek (OK):

Dodaj pole/typ opcjonalny.
Rozszerzenie enum o nowe wartości (z czytnikiem tolerancyjnym).
Dodaj projekcję/zdarzenie alternatywne ('.enriched').
Ograniczenia łagodzące ('minLength', 'max.' z uwzględnieniem ograniczeń).

Niebezpieczne (przerwa):

Usuń/zmień nazwę pola lub zmień ich typ/obowiązkowe.
Zmiana semantyki statusów/kodeków/kolejności w wątkach.
Ponowne użycie znaczników protobufu.
Zmiana klucza podziału w wydarzeniach.

Organizacja rejestrów

Nazewnictwo i adresowanie

Grupy/miejsca: "płatności", "kyc'," audyt ".
Nazwy: "płatność. autoryzowany. v1 „(zdarzenia),” płatności. v1. CaptureRequest '(gRPC),' polecenia. v1. Zamówienie "(JSON Schema).
Major z nazwiska, nieletni w wersji metadanych/schematu.

Metadane

"właściciel" (polecenie), "domena", "slas" (SLO/SLA), "bezpieczeństwo. tier "(PII/PCI)," retencja "," tryb _ kompatybilności "," zachód słońca "," changelog ".

Zarządzanie cyklem życia

Projekt → Przegląd → Zatwierdzony → Wydany → Obniżony → Zachód słońca.
Automatyczne walidatory/lintery, ręczne projektowanie-przegląd (API Guild), uwagi do wydania.

Integracja z CI/CD

1. Pre-commit: lokalne lintery (narzędzia Spectral/Buf/Avro).
2. PR-pipeline: schema-diff → kontrola trybu kompatybilności; blokowanie łamania.
3. Artefakt opublikować: push spójny schemat do rejestru + generować SDK/modele.
4. Runtime-guard (opcjonalnie): Gateway/manufacturer validates loyload against the current scheme.

Przykład kroków w PR:

„openapi-diff --fail-on-breaking”
„buf breaking --against
”
„avro-compat --mode BACKWARD”
generowanie złotych próbek i uruchamianie testów CDC.

Ewolucja systemów: praktyki

Dodatek-pierwszy: нова бола - „opcjonalny/nieullowalny” (JSON), „opcjonalny” (proto3), domyślny МAvro.
Model odwrotnej piramidy: rdzeń jest stabilny, wzbogacenie jest w pobliżu i opcjonalne.
Dual-emit/dual-write for major: publikujemy równolegle 'v1' i 'v2'.
Plan zachodu słońca: daty, zastosowania, ostrzeżenia, adaptery.
Tolerancyjny czytnik: klienci ignorują nieznane pola i prawidłowo obsługują nowe enum.

Przykłady systemów i kontroli

Schemat JSON (fragment, pole addytywne)

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
}

💡 Dodano 'risk _ score' opcjonalnie → BACKWARD jest kompatybilny.

Avro (domyślnie dla kompatybilności)

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 (nie stosować ponownie)

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

Rejestr zdarzeń i podział

Nazywanie zdarzeń: 'domena. działania. v {major} '("płatność. schwytany. v1 ").
Klucz podziału jest częścią umowy ('payment _ id',' user _ id').
Rdzeń vs Wzbogacony: '.v1' (rdzeń) i '.enriched. v1 "(szczegóły).
Zgodność rejestru: tryby na poziomie tematu/typu; CI odmawia niezgodnych ze wspólnym rynkiem zmian.

Zarządzanie migracją

Rozwiń → Migrate → Umowa (REST/gRPC):

1. Dodaj pola/tabele 2) zacznij pisać/czytać nowe pola; 3) usunąć stare po zachodzie słońca.

Podwójne emisje (zdarzenia): równoległe do 'v1 '/' v2', migracja konsumentów/projekcja, a następnie usunięcie 'v1'.
Powtórka: reasembling projekcje z dziennika do nowego schematu (tylko z kompatybilności i migrantów).
Adaptery: bramki/serwery proxy, które tłumaczą 'v1 i v2' dla złożonych klientów.

Bezpieczeństwo i zgodność

Etykiety PII/PCI na schemacie: 'x-pii: true', 'x-sensitivity: high'.
Polityka dostępu: kto może publikować/modyfikować programy (RBAC), podpisywać wersje.
Kryptografia: podpis wersji schematu, immutable audits logs (WORM).
Prawo do bycia zapomnianym: określić pola, które wymagają szyfrowania/usunięcia krypto; wskazówki w rejestrze.

Obserwacja i audyt

Deski rozdzielcze: liczba zmian, typy (drobne/duże), udział odrzuconych PRS, wykorzystanie wersji.
Ścieżka audytu: kto zmienił program, linki do PR/ADR, związane z wydaniem.
Metryki runtime: procent wiadomości, które nie zostały zatwierdzone; incydenty kompatybilności.

Narzędzia (stos próbki)

OpenAPI/JSON Schemat: Spectral, OpenAPI Diff, Schemathesis.
Protobuf/gRPC: Buf, buf-breaking, protoc linters.
Avro/Events: Confluent/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: Inspektor GraphQL, GraphQL Codegen.
Rejestry/katalogi: Rejestr Artifact, Rejestr oparty na Git, Katalog Backstage, niestandardowy interfejs użytkownika.
Dokumentacja: Redocly/Stoplight, Swagger-UI, GraphiQL.

Anty-wzory

Swagger-wash: program nie odzwierciedla rzeczywistości usługi (lub odwrotnie).
Wyłączona kontrola kompatybilności: „pilne” → produkt pęka.
Ponowne użycie znaczników protobufu: cicha korupcja danych.
Tryb kompatybilności pojedynczej „dla wszystkiego”: różne domeny wymagają różnych trybów.
Surowe CDC jako systemy publiczne: wyciek modelu DB, niemożność ewolucji.

Lista kontrolna wdrażania

Zdefiniowany format artefaktu i tryb kompatybilności według domeny.
Lintery i schema-diff są skonfigurowane w CI, PR jest zablokowany podczas łamania.
Włączone dla tolerancyjnego czytnika klienta; „additwieWłaściwości = true” (w stosownych przypadkach).
Główne zmiany przechodzą przez RFC/ADR, istnieje plan zachodu słońca i dual-emit/dual-write.
Obwody są oznaczone poziomami PII/PCI i dostępu; włączony jest audyt.
Użycie wersji i awarie kompatybilności desek rozdzielczych.
Generowanie SDK/modeli z rejestru jest częścią rurociągu.
Dokumentacja i złote próbki aktualizowane automatycznie.

NAJCZĘŚCIEJ ZADAWANE PYTANIA

Czy bez rejestru można przechowywać schematy w Git?
Tak, ale rejestr dodaje interfejsy API kompatybilności, wyszukiwanie, metadane, scentralizowaną politykę i walidację on-the-fly. Najlepszą opcją jest Git jako magazyn + interfejs użytkownika/zasady na górze.

Jak wybrać tryb kompatybilności?
Spójrz na kierunek zmian: jeśli producent rozszerzy ładunek - WSTECZ. Dla publicznego API/SDK - FULL. Dla szybkich prototypów - tymczasowo NONE (nie na tułowiu).

Co zrobić, jeśli to konieczne?
Przygotowanie v2: podwójna/podwójna emisja, daty zachodu słońca, adaptery, telemetria użytkowania, przewodniki migracji.

Czy muszę sprawdzać ładunek w czasie trwania?
W przypadku domen krytycznych tak: zapobiega to śmieciom i przyspiesza diagnostykę.

Wynik

Rejestr schematu przekształca ewolucję danych z ryzykownej improwizacji w proces możliwy do zarządzania: jednolite zasady interoperacyjności, zautomatyzowane walidacje, zrozumiałe wersje i przejrzystą historię. Dodaj do niego dyscyplinę pierwszego dodatku, tolerancyjnego czytelnika, podwójnego emitowania i zachodu słońca - a Twoje kontrakty szybko się rozwijają, bez awarii i incydentów nocnych.