Scheme-Register und Datenentwicklung

Warum Sie ein Scheme-Register benötigen

Das Scheme-Register ist eine zentrale Quelle der Wahrheit für Datenverträge (APIs, Ereignisse, Threads, Nachrichten, Speicher), die Folgendes bietet:

Vorhersehbare Entwicklung: Kompatibilitätsregeln und automatische Überprüfung des „Abbruchs“.
Wiederholbarkeit und Transparenz: Versionsgeschichte, wer/wann/warum geändert.
Standardisierung: einheitliche Namen, Fehlerformate, Trace-Felder, PII-Tags.
Integration mit CI/CD: Blockierung von Breaking-Änderungen vor der Produktion.

Das Register verbindet Protocol-first und vertragliche Kompatibilität und macht Änderungen schnell und sicher.

Formate und Anwendungen

JSON Schema: REST/HTTP-Payloads, Dokumente, Konfigurationen.
Avro: Event-Busse (Kafka/Pulsar), kompakt/Evolution über Feld-ID.
Protobuf: gRPC/RPC, binär-effizient, strenge Tags.
GraphQL SDL: Schema der Typen und Direktiven, Evolution durch'@ deprecated'.
SQL DDL als Artefakt: Wir erfassen vereinbarte Darstellungen (z.B. externe Vitrinen) - mit Vorsicht.

💡 Eine Registry kann mehrere Artefakttypen gleichzeitig speichern, jedoch mit separaten Kompatibilitätsrichtlinien.

Kompatibilitätsmodi

BACKWARD: Neue Schaltungen lesen alte Daten/Nachrichten. Geeignet für einen Produzenten, der Payload additiv erweitert.
VORWÄRTS: Alte Verbraucher lesen neue Daten korrekt (erfordert einen toleranten Leser).
FULL: kombiniert beides (strenger, bequemer für öffentliche Aufträge).
KEINE: keine Kontrollen - nur für Sandkästen.

Empfehlungen:

Events: häufiger BACKWARD (der Produzent erweitert payload optional).
Öffentliche APIs: FULL oder BACKWARD + strenger toleranter Leser auf Clients.
Interne Prototypen: vorübergehend NONE, aber nicht auf trunk.

Sichere (additive) vs. gefährliche Änderungen

Additiv (OK):

Fügen Sie ein optionales Feld/Typ hinzu.
enum mit neuen Werten erweitern (bei tolerantem Reader).
Hinzufügen einer alternativen Projektion/eines alternativen Ereignisses ('.enriched').
Lockerung der Beschränkungen ('minLength', 'maximum' ↑, aber nicht ↓).

Gefährlich (gebrochen):

Löschen/Umbenennen von Feldern oder Ändern des Feldtyps/der Pflichtfelder.
Änderung der Semantik von Status/Codecs/Reihenfolge in Threads.
Neuverwendung von Protobuf-Tags.
Änderung des Partitionierungsschlüssels in Ereignissen.

Organisation des Registers

Namensgebung und Adressierung

Gruppen/Räume: 'payments', 'kyc', 'audit'.
Namen: "Zahlung. authorized. v1` (events), `payments. v1. CaptureRequest` (gRPC), `orders. v1. Order` (JSON Schema).
Dur im Namen, Moll in Metadaten/Version des Schemas.

Metadaten

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

Lebenszyklusmanagement

Draft → Review → Approved → Released → Deprecated → Sunset.
Automatische Validatoren/Linter, manuelle Design-Überprüfung (API Guild), Release Notes.

Integration in CI/CD

1. Pre-commit: lokale Linter (Spectral/Buf/Avro Tools).
2. PR-Pipeline: schema-diff → Überprüfung des Kompatibilitätsmodus; Wir blockieren das Breaking.
3. Artifact publish: Push eines konsistenten Schemas in die Registry + Generierung von SDKs/Modellen.
4. Runtime-guard (optional): Das Gateway/der Produzent validiert payload gegen das aktuelle Schema.

Beispiel für PR-Schritte:

`openapi-diff --fail-on-breaking`
`buf breaking --against
`
`avro-compat --mode BACKWARD`
Erzeugung von goldenen Proben und Ausführung von CDC-Tests.

Entwicklung der Systeme: Praktiken

Additive-first: новые поля — `optional/nullable` (JSON), `optional` (proto3), default в Avro.
Umgekehrtes Pyramidenmodell: Der Kern ist stabil, die Anreicherungen sind nebeneinander und optional.
Dual-emit/dual-write für major: parallel veröffentlichen wir 'v1' und 'v2'.
Sunset-Plan: Termine, Nutzung, Warnungen, Adapter.
Tolerant reader: Kunden ignorieren unbekannte Felder und verarbeiten neue enum korrekt.

Beispiele für Regelungen und Prüfungen

JSON Schema (Fragment, additives Feld)

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
}

💡 Hinzugefügt 'risk _ score' als optional → BACKWARD kompatibel.

Avro (Standard für Kompatibilität)

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 (Tags nicht überbeanspruchen)

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

Ereignisregister und Partitionierung

Benennung der Ereignisse: 'Domäne. action. v{major}` (`payment. captured. v1`).
Der Partitionierungsschlüssel ist Bestandteil des Vertrages ('payment _ id', 'user _ id').
Core vs Enriched: ".v1" (Kernel) und ".enriched. v1'(Einzelheiten).
Kompatibilität im Register: Modi auf Themen-/Typebene; CI lehnt inkompatible Änderungen ab.

Migrationen verwalten

Expand → Migrate → Contract (REST/gRPC):

1. Felder/Tabellen hinzufügen; 2) beginnen, neue Felder zu schreiben/zu lesen; 3) entfernen Sie das alte nach Sonnenuntergang.

Dual-emit (Events): parallel zu 'v1 '/' v2', Migration von Consumern/Projektionen, dann Rückzug 'v1'.
Replay: Neuzusammenstellen von Projektionen aus dem Protokoll in ein neues Schema (nur mit Kompatibilität und Migratoren).
Adapter: Gateway/Proxy, die „v1↔v2“ für komplexe Clients übersetzen.

Sicherheit und Compliance

PII/PCI-Tags im Schema: „x-pii: true“, „x-sensitivity: high“.
Zugriffsrichtlinien: Wer kann Diagramme (RBACs) veröffentlichen/ändern, um Releases zu signieren.
Kryptographie: Signieren von Schemaversionen, unveränderliche Prüfprotokolle (WORM).
Recht auf Vergessenwerden: Geben Sie die Felder an, die Verschlüsselung/Krypto-Löschung erfordern; Führung im Register.

Beobachtbarkeit und Audit

Dashboards: Anzahl der Änderungen, Typen (minor/major), Anteil der abgelehnten PRs, Versionsverwendung.
Audit-Trail: Wer hat das Schema geändert, Links zu PR/ADR, Related Release.
Laufzeitmetriken: Prozentsatz der nicht validierten Nachrichten; Kompatibilitätsvorfälle.

Werkzeuge (Beispielstapel)

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.
Register/Verzeichnisse: Artifact Registry, Git-basierte Registry, Backstage-Katalog, benutzerdefinierte Benutzeroberfläche.
Dokumentation: Redocly/Stoplight, Swagger-UI, GraphiQL.

Antimuster

Swagger-wash: Das Schema spiegelt nicht die Realität des Dienstes wider (oder umgekehrt).
Deaktivierte Kompatibilitätsprüfung: „muss dringend sein“ → die Lücke bricht.
Überverwendung von Protobuf-Tags: Leiser Datenverderb.
Ein einziger Kompatibilitätsmodus „für alles“: Verschiedene Domains erfordern unterschiedliche Modi.
Rohe CDCs als öffentliche Schemata: Leck des OBD-Modells nach außen, Unmöglichkeit der Evolution.

Checkliste Umsetzung

Artefaktformat und Kompatibilitätsmodus nach Domäne definiert.
Linters und Schema-Diff in CI sind konfiguriert, PR wird beim Breaking blockiert.
Toleranter Reader bei Kunden aktiviert; 'additionalProperties = true' (falls zutreffend).
Die großen Änderungen laufen über RFC/ADR, es gibt einen Sunset-Plan und Dual-Emit/Dual-Write.
Die Systeme sind mit PII/PCI und Zugriffsebenen gekennzeichnet. Audit ist aktiviert.
Dashboards für Versionsverwendung und Kompatibilitätsfehler.
Die Generierung von SDKs/Modellen aus dem Register ist Teil der Pipeline.
Dokumentation und goldene Proben werden automatisch aktualisiert.

FAQ

Ist es möglich, ohne Registrierung - Diagramme in Git zu speichern?
Ja, aber die Registry fügt Kompatibilitäts-APIs, Suche, Metadaten, zentrale Richtlinien und „On-the-fly“ -Validierung hinzu. Die beste Option ist Git als Speicher + UI/Richtlinien oben.

Wie wähle ich den Kompatibilitätsmodus?
Schauen Sie sich die Richtung des Wandels an: Wenn der Produzent payload erweitert - BACKWARD. Für öffentliche API/SDK - FULL. Für schnelle Prototypen - vorübergehend NONE (nicht auf trunk).

Was tun, wenn ein Bruch notwendig ist?
Wir bereiten v2 vor: Dual-Emit/Dual-Run, Sunset-Dates, Adapter, Nutzungstelemetrie, Migrations-Guids.

Muss ich payload in rantayme validieren?
Für kritische Domains ja: Es verhindert Junk-Nachrichten und beschleunigt die Diagnose.

Ergebnis

Das Scheme-Register verwandelt die Entwicklung von Daten von riskanter Improvisation in einen überschaubaren Prozess: einheitliche Kompatibilitätsregeln, automatische Überprüfungen, verständliche Versionen und eine transparente Historie. Fügen Sie die Disziplin additive-first, tolerant reader, dual-emit und sunset hinzu - und Ihre Verträge werden sich schnell entwickeln, ohne Entzugserscheinungen oder nächtliche Zwischenfälle.