Wenn ein CRM ein ERP versorgt, ein Shop Bestellungen an die Logistik sendet oder eine interne Anwendung Ereignisse für andere Systeme veröffentlicht, hängt die Integration von mehr ab als von einer URL, einer Queue oder einer gemeinsam genutzten Datei. Sie hängt davon ab, dass alle Beteiligten Daten im Laufe der Zeit auf dieselbe Weise interpretieren. Datenverträge für Integrationen machen diese Erwartung zu expliziten, überprüfbaren und steuerbaren Regeln.
Ihr Ziel besteht nicht darin, eine Schnittstelle einmalig zu dokumentieren, sondern zu verhindern, dass eine scheinbar kleine Änderung — das Umbenennen eines Feldes, die Zulassung eines neuen Status oder die Änderung einer Währungseinheit — stille Fehler, erneute Verarbeitung oder falsche Geschäftsentscheidungen verursacht. Sie sind besonders nützlich, wenn verschiedene Teams, Anwendungen von Drittanbietern und Bereitstellungen mit unabhängigen Zeitplänen beteiligt sind.
Was ist ein Datenvertrag und welches Problem löst er?
Ein Datenvertrag definiert die operative Vereinbarung zwischen demjenigen, der Informationen erzeugt, und demjenigen, der sie nutzt. Er ist auf eine Serviceantwort, ein Ereignis, eine periodische Datei, eine gemeinsam genutzte Tabelle oder eine Queue-Nachricht anwendbar. Er beschreibt, was geliefert wird, was es bedeutet, unter welchen Bedingungen es gültig ist und wie es sich weiterentwickeln wird.
Beispielsweise muss eine Bestellnachricht mit orderId, status und amount präzisieren, ob der Betrag in Einheiten oder Cent angegeben wird, welche Währung gilt, welche Status zulässig sind, ob eine stornierte Bestellung den Betrag null haben kann und ob dieselbe Nachricht mehr als einmal eintreffen kann. Ohne diese Regeln können zwei Systeme dasselbe JSON technisch akzeptieren und dennoch inkompatibel handeln.
Der Vertrag reduziert drei häufige Risiken:
- Direkte Ausfälle: Ein Consumer kann geänderte Daten nicht deserialisieren, validieren oder verarbeiten.
- Semantische Fehler: Das Format scheint korrekt, doch die Bedeutung eines Feldes oder einer Geschäftsregel ändert sich.
- Unsichtbare Abhängigkeiten: Ein Producer weiß nicht, dass ein Feld, ein Wert oder ein Verhalten von anderen Consumern verwendet wird.
Dokumentation, Schema und operativer Vertrag
Die Dokumentation erläutert, wie eine Integration funktionieren sollte. Ein Schema formalisiert einen Teil dieser Erklärung: Struktur, Namen, Typen, Pflichtfelder und je nach Technologie Einschränkungen. Beides ist notwendig, reicht jedoch nicht aus, um eine Integration sicher zu betreiben.
Der operative Vertrag verbindet das Schema mit Entscheidungen, die geprüft und getestet werden können: Eigentümer, bekannte Consumer, Kompatibilitätsrichtlinie, Versionierung, semantische Regeln, Mindestqualität, Fehlerbehandlung und Änderungsverfahren. Er kann mit OpenAPI, AsyncAPI, JSON Schema, Avro, Protobuf, SQL oder einer anderen Spezifikation dargestellt werden, aber das Werkzeug ersetzt diese Entscheidungen nicht.
Ein nützlicher Vertrag sollte mindestens Folgendes enthalten:
- Identität und Umfang: Name, Zweck, Kanal, Producer, Verantwortlicher und Klassifizierung der Sensibilität.
- Struktur: Felder, Typen, Kardinalität, Pflichtstatus, Formate und gültige Beispiele.
- Semantik: Bedeutung, Einheit, Zeitzone, Währung, Wertekatalog und Berechnungsregeln.
- Qualität: Eindeutigkeit, Bereiche, Beziehungen zwischen Feldern, erwartete Aktualität und Reihenfolge, wenn relevant.
- Betrieb: Häufigkeit, Größenlimits, Zustellreihenfolge, Wiederholungsversuche, Aufbewahrung und Incident-Kanal.
- Weiterentwicklung: Version, kompatible Änderungen, Änderungen mit Koordinierungsbedarf und Auslaufzeitraum.
Kompatibilität: Änderungen aus einer expliziten Perspektive bewerten
Die Terminologie zur Kompatibilität kann zwischen Teams variieren. Um Fehlentscheidungen zu vermeiden, empfiehlt es sich, die übliche Perspektive des Lesens von Schemata zu übernehmen, die von zahlreichen Schema-Registries verwendet wird: Abwärtskompatibilität bedeutet, dass das neue Schema oder der neue Consumer Daten lesen kann, die mit dem vorherigen Schema erzeugt wurden; Vorwärtskompatibilität bedeutet, dass das vorherige Schema oder der vorherige Consumer Daten lesen kann, die mit dem neuen Schema erzeugt wurden. Vollständige Kompatibilität erfordert beide Richtungen.
Aus dieser Definition lässt sich das tatsächliche Verhalten nicht allein durch die Betrachtung einer abstrakten Regel ableiten. Es muss anhand des Formats, des Serialisierers, des Leseschemas und der konkreten Implementierung des Consumers überprüft werden. Das Hinzufügen eines optionalen Feldes mit Standardwert kann beispielsweise abwärtskompatibel sein, wenn die neue Version dessen Fehlen beim Lesen alter Daten ergänzen kann. Ein alter Consumer kann die neue Nachricht jedoch nur lesen, wenn seine Technologie und Implementierung unbekannte Felder ignorieren oder wenn sein Leseschema dieses Feld mit einem Standardwert korrekt auflöst. Dies darf nicht ohne einen Test angenommen werden.
Stellen Sie vor der Genehmigung einer Änderung konkrete Fragen: Kann die neue Version bereits gespeicherte Nachrichten verarbeiten? Kann die vorherige Version während einer schrittweisen Bereitstellung weiterhin gesendete Nachrichten verarbeiten? Was geschieht mit externen Consumern, die nicht im gleichen Tempo aktualisiert werden? Die Antwort muss aus repräsentativen Tests hervorgehen, nicht nur aus dem Kompatibilitätslabel der Registry.
Als praktische Regel gelten das Hinzufügen tatsächlich optionaler Felder, die Erweiterung nicht interpretierter Metadaten oder die Korrektur von Beschreibungen häufig als Änderungen mit geringerem Risiko. Das Entfernen oder Umbenennen von Feldern, das Ändern von Typen, das Einschränken von Bereichen, das Ändern von Einheiten, das Neuinterpretieren von Nullwerten oder das Einführen von Aufzählungswerten, die eine andere Logik auslösen, erfordern in der Regel eine neue Version und Koordinierung. Ein veraltetes Feld vorübergehend beizubehalten und ein Datum für seine Entfernung zu veröffentlichen, ermöglicht einen sichereren Übergang als seine sofortige Entfernung.
Design je nach Austauschtyp
Dasselbe Prinzip nimmt je nach Mechanismus unterschiedliche Formen an. Identifizieren Sie bei Ereignissen den eingetretenen Sachverhalt, den Geschäftszeitpunkt, die Quelle, die Ereigniskennung und die betroffene Entität. Geben Sie an, ob das Ereignis unveränderlich ist, ob es ungeordnet eintreffen kann und ob Korrekturereignisse vorhanden sind.
Bei mindestens einmaliger Zustellung benötigt der Consumer eine überprüfbare Strategie, um Duplikate zu erkennen oder zu tolerieren. Er kann eine Ereigniskennung verwenden, die in einem Deduplizierungsregister gespeichert wird, einen Geschäftsschlüssel mit idempotenten Operationen, eine Speicherbeschränkung oder einen gleichwertigen vereinbarten Mechanismus. Ein Idempotenzschlüssel ist eine häufige Option, aber keine allgemeingültige Anforderung. Wichtig ist, zu definieren, welche Duplikate erwartet werden, wie lange sie erkannt werden und welches Ergebnis ihre erneute Verarbeitung erzeugen muss.
Bei synchronen Serviceantworten muss der Vertrag Geschäftsdaten, fachliche Fehler und technische Ausfälle unterscheiden. Es ist vorzuziehen, Codes, Fehlerstruktur, sichere Felder für die Diagnose und Bedingungen für Wiederholungsversuche zu definieren. Bei periodischen Datenladungen geben Sie den zeitlichen Stichtag, die Zeitzone, an, ob die Datei eine vollständige oder inkrementelle Ladung enthält, den Abgleichschlüssel und das Verhalten bei wiederholten oder fehlenden Datensätzen an.
Vertragstests vor und nach der Produktion
Vertragstests automatisieren die Überprüfung, dass Producer und Consumer die Vereinbarung einhalten. Validieren Sie in der Entwicklung gültige und ungültige Beispiele gegen das Schema und die relevanten semantischen Regeln. Beziehen Sie Grenzfälle ein: zulässige Nullwerte, unbekannte Werte, Dezimalzahlen, Datumsangaben mit Zeitzone und Kombinationen abhängiger Felder.
In der kontinuierlichen Integration muss die Vertragsänderung mit der zuletzt veröffentlichten Version verglichen werden. Die Kontrolle kann inkompatible Änderungen blockieren, eine neue Version verlangen oder die Genehmigung des Verantwortlichen erfordern. Es empfiehlt sich außerdem, Referenz-Consumer oder mit kritischen Consumern vereinbarte Tests anhand von Testdaten auszuführen, die von der neuen Version erzeugt wurden.
Testen Sie vor der Produktion das Zusammenspiel der Versionen, das während der Bereitstellung tatsächlich bestehen wird. Beobachten Sie nach der Veröffentlichung Raten fehlgeschlagener Validierungen, in Quarantäne gesendete Nachrichten, Deserialisierungsfehler, Verarbeitungsverzögerungen und den Anteil unbekannter Werte. Erfassen Sie technische Kennungen, Vertragsversion, Fehlertyp und Quelle; vermeiden Sie die Aufnahme personenbezogener Daten, Geheimnisse oder vollständiger Nutzlasten, wenn sie für die Diagnose nicht unverzichtbar sind.
Änderungssteuerung, Ausnahmen und Nachverfolgbarkeit
Ein schlanker und expliziter Ablauf verhindert, dass der Vertrag zu einem vergessenen Dokument wird. Der Producer schlägt die Änderung mit ihrer Begründung, den erwarteten Auswirkungen, einem Vorher-Nachher-Beispiel, der Kompatibilitätsklassifizierung und einem Auslaufplan vor. Die Verantwortlichen der betroffenen Consumer prüfen Semantik und Tests. Ein benannter Eigentümer genehmigt, veröffentlicht die Version und kommuniziert das Einführungsfenster.
Auch Ausnahmen müssen definiert sein. Wenn ein Wert außerhalb des Bereichs eintrifft, muss nicht immer die gesamte Datenladung abgelehnt werden: Je nach Geschäftsrisiko kann sie in Quarantäne verschoben, zur Überprüfung markiert oder mit einem Qualitätssignal akzeptiert werden. Legen Sie für unbekannte Katalogwerte fest, ob der Consumer sie ignorieren, beibehalten, ein sicheres Verhalten anwenden oder den Prozess anhalten soll. Unterscheiden Sie sorgfältig zwischen einem fehlenden Feld, einem Feld mit null und einem leeren Wert: Sie können unterschiedliche Situationen ausdrücken.
Führen Sie abschließend ein versioniertes Register der Verträge, Kompatibilitätsentscheidungen, Genehmigungen, Deprecation-Daten und Testnachweise. Diese Nachverfolgbarkeit ermöglicht die Beantwortung, wer was geändert hat, warum es als sicher galt und welche Consumer angepasst werden mussten. So hängt die Weiterentwicklung nicht mehr von manuellen Prüfungen ab, sondern wird zu einer überprüfbaren technischen Disziplin.