Eine Integration kann weiterhin erfolgreich antworten und dennoch Daten fehlerhaft verarbeiten. Ein Anbieter ändert die Bedeutung eines Feldes, eine Plattform im Unternehmensumfeld bietet zwei API-Versionen an oder ein Client verwendet eine abweichende Authentifizierungskonfiguration. Eine Kompatibilitätsmatrix für Softwareintegrationen hält fest, welche Kombinationen die Anwendung unterstützt, welche validiert wurden und welche Einschränkungen gelten.
Sie ist weder eine Liste aller existierenden Produkte noch ein Versprechen universeller Funktionsfähigkeit. Sie ist ein Hilfsmittel, um zu entscheiden, was abgedeckt werden soll, wie Abweichungen erkannt werden und wer handeln muss, wenn sich eine Abhängigkeit ändert. In PHP-Anwendungen kann sie das technische Inventar mit automatisierten Tests, Monitoring und Änderungsverfahren verknüpfen.
Was Kompatibilität bei einer Integration bedeutet
Kompatibilität umfasst mehr als die Version einer API. Mindestens fünf Dimensionen sollten getrennt betrachtet werden:
- Format: Struktur von Anfrage und Antwort, Inhaltstypen, Kodierung und Serialisierung.
- Felder: Namen, Typen, Pflichtangaben, Nullwerte, zulässige Werte und Validierungsregeln.
- Semantik: Bedeutung der einzelnen Daten und die Einheiten oder Zeitzone, in denen sie interpretiert werden. Ein vorhandenes Feld kann seine Bedeutung geändert haben.
- Zugriff: Authentifizierungsmethode, Berechtigungen, Ablauf von Zugangsdaten und erforderliche Scopes.
- Verhalten: Fehlercodes, Anfragebegrenzungen, Ereignisreihenfolge, Wiederholungsversuche und Idempotenz.
Die Matrix sollte zwischen additiven und inkompatiblen Änderungen unterscheiden. Das Hinzufügen eines optionalen Feldes wirkt sich möglicherweise nicht auf den Verbraucher aus, wenn dieser unbekannte Felder ignoriert; die Umbenennung eines Pflichtfeldes kann ihn dagegen beeinträchtigen. Die Bewertung hängt vom tatsächlichen Integrationsvertrag und davon ab, wie der Client-Code geschrieben ist.
Abhängigkeiten und relevante Kombinationen erfassen
Beginnen Sie mit einer Auflistung jedes externen Systems und der jeweiligen Schnittstelle: API, Webhook, importierte Datei, Queue, Bibliothek oder Connector. Erfassen Sie, wer das System betreut, welche PHP-Anwendung es nutzt, welche Daten ausgetauscht werden und welche Geschäftsvorgänge davon abhängen. Berücksichtigen Sie Umgebungen und Konfigurationen, die das Verhalten beeinflussen können, etwa Region, Authentifizierungsmethode oder Datumsformat.
Ermitteln Sie anschließend die beobachteten und offiziell unterstützten Varianten: API-Versionen, Plattformversionen, Payload-Schemas und Zugriffskonfigurationen. Gehen Sie nicht davon aus, dass jede theoretisch mögliche Kombination relevant ist. Priorisieren Sie anhand konkreter Anhaltspunkte:
- Volumen des Datenverkehrs oder der betroffenen Geschäftsvorgänge.
- Vorkommen bei aktiven Kunden, in Regionen oder Installationen.
- Auswirkungen eines Fehlers und Möglichkeit, den Vorgang wiederherzustellen oder zu wiederholen.
- Änderungshistorie, Vorfälle und bekannte Unterschiede zwischen Versionen.
- Verfügbarkeit einer Testumgebung oder repräsentativer Daten.
Bei vielen Kombinationen müssen nicht alle getestet werden. Legen Sie eine risikobasierte Abdeckung fest: am häufigsten verwendete Versionen, neueste Versionen, Supportstufen sowie Kombinationen mit abweichender Authentifizierung oder abweichendem Schema. Halten Sie nicht getestete Kombinationen fest; Schweigen darf nicht als bestätigte Kompatibilität verstanden werden.
Eine nützliche und umsetzbare Matrix definieren
Eine Zeile steht für ein überprüfbares Szenario, nicht lediglich für den Namen eines Anbieters. Sie kann System, Version, Vorgang, Format, Authentifizierung, Supportstatus, Validierungsgrad, Einschränkungen, Verantwortliche und Prüfdatum enthalten. Ergänzen Sie einen Verweis auf den automatisierten Test, das Fixture oder den Validierungsnachweis, der den Status belegt.
Verwenden Sie eindeutige Statusangaben. Zum Beispiel: unterstützt und getestet, mit dokumentierten Einschränkungen unterstützt, Validierung ausstehend oder nicht mehr unterstützt. Unterscheiden Sie die vom Anbieter erklärte Kompatibilität von der durch Ihr Team validierten. Eine Version kann laut Drittanbieter offiziell kompatibel sein, ohne in Ihrer Anwendung getestet worden zu sein.
Legen Sie außerdem Grenzen fest: Mindest- und Höchstversionen, abgedeckte Vorgänge, nicht unterstützte Verhaltensweisen und Voraussetzungen für die Aktivierung der Integration. Benennen Sie Verantwortliche für die Aktualisierung der Matrix und die Genehmigung von Ausnahmen. Ohne klare Zuständigkeit veraltet das Dokument leicht, auch wenn die Tests weiterhin ausgeführt werden.
Priorisierte Szenarien in Tests umsetzen
Tests sollten Verträge und relevante Ergebnisse prüfen und nicht nur sicherstellen, dass eine Antwort den HTTP-Status 200 liefert. Validieren Sie für jedes priorisierte Szenario Struktur, Typen, Pflichtfelder, semantische Regeln und das Verhalten bei erwarteten Fehlern. Berücksichtigen Sie gegebenenfalls Paginierung, Begrenzungen, Duplikate, Wiederholungsversuche und abgelaufene Authentifizierung.
In einer PHP-Anwendung können Unit-Tests Adapter und Mapper anhand versionierter Fixtures prüfen. Vertragstests überprüfen, ob Anfragen und Antworten der erwarteten Vereinbarung entsprechen. Integrationstests erproben die Kommunikation mit einer kontrollierten Umgebung des Anbieters, sofern verfügbar. Jede Ebene beantwortet andere Fragen: Ein Fixture beweist nicht, dass der Remotedienst weiterhin verfügbar ist, und ein Test gegen den Dienst ersetzt keine deterministischen Tests der Datenumwandlung.
Speichern Sie repräsentative und, sofern erforderlich, anonymisierte Fixtures. Vermeiden Sie Tokens, unnötige personenbezogene Daten oder vertrauliche Informationen. Wenn der Anbieter Schemas häufig ändert, kann ein automatisierter Vertragsvergleich Unterschiede aufzeigen; die menschliche Prüfung muss entscheiden, ob diese unbedenklich, inkompatibel oder geschäftlich relevant sind.
Inkompatible Änderungen rechtzeitig bewältigen
Richten Sie Signale zur Erkennung von Änderungen ein: Mitteilungen des Anbieters, neue Dokumentationsversionen, unerwartete Antworten, Validierungsfehler und Fehlermetriken nach Endpoint oder Version. Protokollieren Sie die beobachtete Version oder Variante auf sichere Weise, ohne Zugangsdaten oder sensible Daten offenzulegen, damit sich ein Vorfall einem konkreten Szenario zuordnen lässt.
Tritt eine Abweichung auf, klassifizieren Sie sie, bevor Sie den Code anpassen. Es kann genügen, ein zusätzliches Feld zu tolerieren; bei einer Typänderung ist möglicherweise eine explizite Konvertierung erforderlich; eine semantische Änderung kann eine Produktentscheidung erfordern. Halten Sie die Anpassung an einer klar definierten Grenze, etwa in einem Client oder Adapter, und vermeiden Sie, Besonderheiten des Anbieters in der gesamten Anwendung zu verbreiten.
Kann ein Update nicht sofort aktiviert werden, definieren Sie einen Übergang: Tests mit der neuen Version, kontrolliertes Deployment, Beobachtung von Fehlern und ein Verfahren für den Rollback. Code bereitzustellen ist nicht dasselbe, wie eine neue Route oder einen neuen Zugang für alle Nutzer zu aktivieren; sofern die Architektur es zulässt, kann diese Aktivierung schrittweise erfolgen. Bewahren Sie bei laufenden Vorgängen die Kompatibilität mit bereits gesendeten Nachrichten und vermeiden Sie beim Wiederholen nicht idempotenter Aktionen eine erneute Ausführung.
Varianten außer Betrieb nehmen, ohne Abläufe zu unterbrechen
Die Unterstützung einer Version einzustellen, erfordert klare Kriterien: Ende des Anbieter-Supports, verbleibende Nutzung, Aufwand für die Pflege von Tests, Sicherheitsrisiken oder die Unmöglichkeit, das Verhalten zu gewährleisten. Messen Sie vor der Außerbetriebnahme die Nutzung und ermitteln Sie die betroffenen Verbraucher. Eine vereinbarte Frist, die Kommunikation der Änderung und ein Migrationspfad verringern Überraschungen.
Trennen Sie die Außerbetriebnahme einer Variante von der sofortigen Löschung von Daten oder der Beendigung ausstehender Prozesse. Gibt es Queues, Synchronisierungen oder geplante Jobs, prüfen Sie, ob diese sicher abgeschlossen, wiederholt oder migriert werden können. Protokollieren Sie nach Ablauf der Frist die Zurückweisung klar und nachvollziehbar; warnen Sie vor einer stillen Verschlechterung, die bei einer veralteten Integration zu Datenkorruption führen kann.
Checkliste bei Änderungen an einer Abhängigkeit
- Wurde das Inventar der betroffenen Versionen, Formate, Authentifizierungsverfahren und Vorgänge aktualisiert?
- Wurden die Verträge verglichen und Änderungen an Typen und Semantik bewertet?
- Gibt es Fixtures und Tests für die priorisierten Kombinationen und Fehlerfälle?
- Wurden Berechtigungen, Geheimnisse, personenbezogene Daten und Anfragebegrenzungen überprüft?
- Sind Verantwortliche, Aktivierungskriterien, Monitoring und Rollback festgelegt?
- Wurden Kunden oder Prozesse ermittelt, die vor der Außerbetriebnahme einer Variante migriert werden müssen?
- Hält die Matrix fest, was getestet wurde, was noch aussteht und wann sie erneut geprüft werden muss?
Eine Kompatibilitätsmatrix für Softwareintegrationen ist dann nützlich, wenn sie überprüfbare Entscheidungen unterstützt: Was wird unterstützt, mit welchen Nachweisen, unter welchen Einschränkungen und bis wann? Wird sie zusammen mit den Tests und dem Änderungsprozess gepflegt, lassen sich Überraschungen reduzieren, ohne eine lückenlose Abdeckung anzustreben, die keinen Mehrwert bietet.
