Der gefährlichste Satz in Integrationsprojekten

Aus der Praxis

Wie Integrationsplattformen langsam unwartbar werden

Praxisbeispiel

In einem Integrationsprojekt sollte eine neue Plattform wiederkehrende Anbindungen vereinheitlichen. Der erste Use Case wirkte überschaubar: Daten aus einem System übernehmen, transformieren und für ein anderes System bereitstellen.

Also wurde pragmatisch gestartet. Das war nicht falsch. In echten Projekten ist am Anfang selten alles vollständig spezifiziert.

Dann kam der nächste Fachfall. Dann eine Ausnahme für ein Legacy-System. Dann ein Sonderfall im Mapping. Dann ein technischer Workaround, weil ein angebundenes System sich anders verhielt als erwartet. Dann eine weitere Abweichung, weil ein Prozess fachlich doch nicht ganz gleich funktionierte wie der vorherige.

Jede einzelne Änderung war nachvollziehbar. Keine davon sah gefährlich aus. Aber zusammen entstand Code, bei dem niemand mehr sicher sagen konnte, welche Änderung welche Sonderfälle betrifft.

Das Problem war nicht, dass pragmatisch gestartet wurde. Das Problem war, dass die Struktur nicht mitgewachsen ist.

Integrationsplattformen werden selten auf einen Schlag unwartbar. Sie werden unwartbar, wenn Sonderfälle, Workarounds und fachliche Logik wachsen — aber Spezifikation, Tests und technische Grenzen nicht.

Die strukturelle Ebene

Das eigentliche Risiko liegt nicht im ersten Use Case

Neue Integrationsplattformen entstehen oft unter Zeitdruck. Bestehende Systeme müssen angebunden, Datenmodelle übersetzt, externe APIs integriert und Legacy-Verhalten berücksichtigt werden. Der erste Use Case ist dabei selten das Problem.

Gefährlich wird es, wenn die Plattform nach und nach immer mehr Verantwortung übernimmt: Mapping, fachliche Sonderfälle, technische Workarounds, Fehlerbehandlung, Anbieter-spezifische Abweichungen und Logik, die eigentlich klarer abgegrenzt sein müsste.

Dann funktioniert die Plattform zwar weiter. Aber jede Änderung wird schwieriger. Nicht weil der Code „unschön" ist, sondern weil niemand mehr sicher einschätzen kann, welche Nebenwirkungen eine Anpassung hat.

Meine These

Unwartbarer Integrationscode entsteht selten durch schlechte Entwickler. Er entsteht, wenn Anforderungen wachsen, Sonderfälle ungeordnet eingebaut werden und niemand früh genug entscheidet, wo fachliche Logik endet und technische Integration beginnt.

5 Anti-Patterns aus der Praxis

Wie aus einer nützlichen Plattform ein Sonderfall-Sammelbecken wird

Anti-Pattern #1

„Wir bauen erstmal los" bleibt der dauerhafte Modus

Pragmatisch zu starten ist oft sinnvoll. Das Problem entsteht, wenn aus einem pragmatischen Start nie eine explizite Struktur wird. Der erste Use Case wird zur impliziten Architektur — und jeder neue Fall wird irgendwie daran angehängt.

Code-Beispiel anzeigen

// Typisches Wachstum ohne klare Grenze
if (sourceSystem == "A") {
    mapStandardCase();
} else if (sourceSystem == "B" && customerType == "legacy") {
    applyLegacyWorkaround();
} else if (sourceSystem == "C" && featureFlagEnabled()) {
    mapSpecialCaseForNewProcess();
}

Besser

Nach den ersten Use Cases bewusst nachziehen: Welche Regeln sind Standard? Welche sind Sonderfälle? Welche Logik gehört in die Plattform — und welche nicht?

Anti-Pattern #2

Sonderfälle werden normalisiert

Am Anfang ist ein Sonderfall noch sichtbar. Später steht er einfach mitten in der normalen Logik. Neue Entwickler sehen nicht mehr, ob etwas fachlich gewollt, technisch notwendig oder nur ein historischer Workaround ist.

Code-Beispiel anzeigen

// Der gefährlichste Sonderfall ist der,
// den niemand mehr als Sonderfall erkennt.
applyMappingRules(input);
applyAdditionalRules(input);      // Warum?
applyCompatibilityFix(input);     // Für wen?
normalizeValues(input);           // Fachlich oder technisch?

Besser

Sonderfälle explizit machen: als eigene Regel, eigene Klasse, eigene Testfälle und mit klarer Begründung. Ein Workaround darf existieren — aber er muss als Workaround erkennbar bleiben.

Anti-Pattern #3

Die Integrationsplattform entscheidet fachliche Fragen

Eine Integrationsplattform soll Systeme verbinden, Daten übersetzen und technische Unterschiede kapseln. Sie wird gefährlich, wenn sie zur Ablage für ungeklärte fachliche Entscheidungen wird.

Code-Beispiel anzeigen

// Warnsignal: Die Plattform entscheidet plötzlich fachlich
if (accountStatus == "blocked" && paymentType == "instant") {
    rejectPayment();
}
// Frage: Gehört diese Entscheidung wirklich in die Integration?

Besser

Fachliche Verantwortung klar trennen: Was entscheidet ein Fachservice? Was übersetzt die Integrationsschicht? Was ist nur technischer Adapter-Code?

Anti-Pattern #4

Tests sichern den Happy Path, aber nicht die Varianten

Bei Integrationslogik reicht es nicht, zu prüfen, ob der Standardfall funktioniert. Das Risiko steckt in Kombinationen: Legacy-System plus Sonderprozess plus optionales Feld plus Fehlerfall.

Code-Beispiel anzeigen

// ❌ Testet nur: Standardfall läuft
shouldMapDefaultCaseSuccessfully();

// ✅ Testet: Entscheidungslogik und Varianten
shouldApplyLegacyRuleOnlyForSourceSystemB();
shouldNotApplyWorkaroundForNewProcess();
shouldRejectUnsupportedCombinationExplicitly();

Besser

Tests müssen nicht nur Outputs prüfen, sondern Entscheidungen: Wann greift welche Regel? Welche Kombinationen sind erlaubt? Welche Fälle werden bewusst nicht unterstützt?

Anti-Pattern #5

Refactoring wird zu riskant

Der Endzustand ist nicht einfach „hässlicher Code". Der Endzustand ist Code, den niemand mehr sicher ändern kann. Jede Anpassung wird zum Risiko, weil unklar ist, welche Sonderfälle noch irgendwo daran hängen.

Code-Beispiel anzeigen

// Die eigentliche Frage ist nicht:
"Kann man diesen Code schöner schreiben?"

// Die eigentliche Frage ist:
"Können wir ihn ändern, ohne fachliche Seiteneffekte zu erzeugen?"

Besser

Refactoring braucht fachliche Sicherheit: nachvollziehbare Regeln, gute Testabdeckung, klare Grenzen und eine Struktur, in der neue Fälle nicht automatisch weitere Verzweigungen erzeugen.

Praxis-Framework

Der Sonderlogik-Test für Integrationsplattformen

Diese Fragen helfen, früh zu erkennen, ob eine Integrationsplattform sauber wächst — oder ob sie beginnt, Sonderfälle und Workarounds ungeordnet aufzusammeln.

Frage	Gesundes Signal	Warnsignal
Sind Standardfälle und Sonderfälle getrennt?	Ausnahmen sind explizit modelliert.	Sonderfälle stecken verteilt im Code.
Gibt es klare Verantwortlichkeiten?	Fachlogik, Mapping und technische Adapter sind getrennt.	Die Plattform entscheidet alles.
Sind Workarounds sichtbar?	Temporäre Lösungen sind dokumentiert und begründet.	Workarounds wirken wie normales Verhalten.
Decken Tests echte Varianten ab?	Fehlerfälle, Kombinationen und Sonderfälle sind getestet.	Nur der Happy Path ist abgesichert.
Kann man eine Änderung sicher einschätzen?	Betroffene Regeln und Schnittstellen sind nachvollziehbar.	Jede Änderung fühlt sich wie Glücksspiel an.
Wächst die Struktur mit?	Neue Anforderungen führen zu klaren Erweiterungspunkten.	Neue Anforderungen führen zu weiteren Verzweigungen.

Wenn mehrere Warnsignale zutreffen, ist das kein Zeichen für schlechte Entwickler. Es ist ein Zeichen dafür, dass die Plattform mehr Struktur braucht, bevor sie weiter wächst.

Was saubere Umsetzung konkret bedeutet

Wartbarkeit entsteht nicht am Ende. Sie entsteht beim Implementieren.

Eine Integrationsplattform bleibt nicht automatisch wartbar, nur weil gute Architekturentscheidungen getroffen wurden. Entscheidend ist, wie diese Entscheidungen im Code landen.

Regeln müssen explizit im Code erkennbar sein — nicht nur implizit über verschachtelte Bedingungen.
Sonderfälle brauchen eine klare Begründung, eigene Tests und möglichst klare technische Grenzen.
Mapping, fachliche Entscheidungen und technische Adapter sollten nicht ungeprüft in dieselbe Schicht rutschen.
Tests müssen die Varianten absichern, die später beim Refactoring gefährlich werden.
Dokumentation muss erklären, warum bestimmte Abweichungen existieren — nicht nur, dass sie existieren.
Neue Anforderungen sollten nicht automatisch zu weiteren Verzweigungen führen, sondern zu bewusst gewählten Erweiterungspunkten.

Kurz gesagt

Guter Integrationscode ist nicht der Code, der beim ersten Go-Live am schnellsten funktioniert. Guter Integrationscode ist Code, den ein Team auch Monate später noch sicher ändern, testen und erweitern kann.

Der gefährlichste Satz in Integrationsprojekten:
„Wir bauen erstmal los."

Wie Integrationsplattformen langsam unwartbar werden

Das eigentliche Risiko liegt nicht im ersten Use Case

Wie aus einer nützlichen Plattform ein Sonderfall-Sammelbecken wird

„Wir bauen erstmal los" bleibt der dauerhafte Modus

Sonderfälle werden normalisiert

Die Integrationsplattform entscheidet fachliche Fragen

Tests sichern den Happy Path, aber nicht die Varianten

Refactoring wird zu riskant

Der Sonderlogik-Test für Integrationsplattformen

Wartbarkeit entsteht nicht am Ende. Sie entsteht beim Implementieren.

Wer steckt dahinter

Baut ihr gerade eine Integrationsplattform oder erweitert bestehende Integrationslogik?

Der gefährlichste Satz in Integrationsprojekten:„Wir bauen erstmal los."

Wie Integrationsplattformen langsam unwartbar werden

Das eigentliche Risiko liegt nicht im ersten Use Case

Wie aus einer nützlichen Plattform ein Sonderfall-Sammelbecken wird

„Wir bauen erstmal los" bleibt der dauerhafte Modus

Sonderfälle werden normalisiert

Die Integrationsplattform entscheidet fachliche Fragen

Tests sichern den Happy Path, aber nicht die Varianten

Refactoring wird zu riskant

Der Sonderlogik-Test für Integrationsplattformen

Wartbarkeit entsteht nicht am Ende. Sie entsteht beim Implementieren.

Wer steckt dahinter

Baut ihr gerade eine Integrationsplattform oder erweitert bestehende Integrationslogik?

Der gefährlichste Satz in Integrationsprojekten:
„Wir bauen erstmal los."