Integracja przestaje być szczegółem technicznym, gdy jej pola, kody błędów i reguły dostępu pojawiają się w kontrolerach, usługach aplikacyjnych, modelach i procesach biznesowych. W tym momencie zmiana dostawcy, aktualizacja API lub obsługa zewnętrznego incydentu wymaga modyfikacji części aplikacji, które nie powinny znać tego systemu.
Izolowanie zewnętrznych integracji w PHP polega na ustanowieniu wyraźnej granicy: domena wyraża to, czego potrzebuje, własnym językiem, a warstwa infrastruktury tłumaczy tę potrzebę na konkretny protokół, format i zachowanie dostawcy. Nie chodzi o ukrycie API za klasą o innej nazwie, lecz o niedopuszczenie, by jego decyzje warunkowały całą aplikację.
Kiedy integracja już zanieczyszcza aplikację
Sprzężenie zwykle narasta stopniowo. Zespół korzysta z API z poziomu kontrolera, aby zrealizować pilne wdrożenie; potem inny przepływ wykorzystuje ponownie tego samego klienta; w końcu tablice odpowiedzi i wyjątki SDK stają się niejawnymi zależnościami biznesu.
- Przypadki użycia przyjmują lub zwracają tablice z nazwami pól dostawcy.
- Logika biznesowa porównuje zewnętrzne kody, takie jak
ERR_42lubPENDING_REVIEW. - Kontrolery, komendy i zadania kolejkowe bezpośrednio tworzą żądania HTTP.
- Wyjątki zewnętrznego SDK są przechwytywane poza infrastrukturą.
- Modyfikacja poświadczeń, endpointów lub wersji wymusza edycję wielu modułów.
- Testy domeny potrzebują rzeczywistych połączeń, tokenów lub symulowanych odpowiedzi dostawcy.
Sygnały te nie oznaczają, że należy rozpocząć całkowite przepisanie systemu. Wskazują jednak, że warto nadać integracji priorytet według ryzyka: krytyczności dla biznesu, częstotliwości zmian po stronie dostawcy, liczby wewnętrznych konsumentów, wrażliwości danych i trudności odzyskania sprawności po awarii.
Definiowanie kontraktów w języku biznesu
Wewnętrzny kontrakt, nazywany również portem, powinien opisywać zdolność potrzebną aplikacji, a nie odwzorowanie katalogu operacji zewnętrznego API. Na przykład aplikacja rezerwacyjna może potrzebować „złożyć wniosek o rezerwację”, „sprawdzić jej status” i „anulować ją”. Domena nie musi wiedzieć, że dostawca używa XML, OAuth, numerycznego identyfikatora ani określonej konwencji ponawiania prób.
Port można wyrazić jako interfejs PHP:
interface ReservationGateway
{
public function request(ReservationRequest $request): ReservationResult;
public function status(ReservationReference $reference): ReservationStatus;
public function cancel(ReservationReference $reference): void;
}Typy kontraktu powinny należeć do języka wewnętrznego. ReservationRequest zawiera dane niezbędne do podjęcia decyzji biznesowej; nie powinien obejmować pól uwierzytelniania, nagłówków HTTP ani nazw odziedziczonych po dostawcy. Podobnie wewnętrzna referencja może enkapsulować zewnętrzną tożsamość, nie czyniąc jej dominującą we wszystkich przypadkach użycia.
Elementy granicy integracji
Port, adapter i wewnętrzny DTO
Port jest interfejsem używanym przez aplikację. Adapter jest implementacją komunikującą się z systemem zewnętrznym. Pomiędzy nimi wewnętrzne DTO przenoszą dane w strukturze stabilnej dla aplikacji.
Adapter tłumaczy w obu kierunkach: przekształca wewnętrzny DTO w konkretne żądanie i normalizuje odpowiedź do wyniku, który domena może zinterpretować. Jeżeli dostawca zmieni guest_count na travellers, zmiana powinna pozostać zawarta w tym adapterze.
Konfiguracja, poświadczenia i transport
Endpointy, tokeny, limity czasu, certyfikaty i polityki ponawiania prób są zagadnieniami infrastruktury. Powinny być wstrzykiwane przez konfigurację i pozostawać poza encjami oraz usługami domenowymi. Warto również oddzielić klienta HTTP lub SDK od adaptera: ułatwia to zastępowanie bibliotek, rejestrowanie telemetrii i testowanie mapowania bez zależności od rzeczywistego transportu.
Tłumaczenie błędów i stany niepewne
Nie wszystkie awarie wymagają takiego samego traktowania. Błąd walidacji zgłoszony przez dostawcę może być możliwy do naprawienia przez użytkownika; błąd uwierzytelniania wymaga interwencji operacyjnej; przekroczenie limitu czasu może pozostawić niepewny stan, ponieważ dostawca mógł przetworzyć żądanie.
Wewnętrzny kontrakt powinien reprezentować te różnice bez przepuszczania obcych wyjątków. Na przykład adapter może przekształcić odpowiedź walidacyjną w ReservationRejected, problem tymczasowy w TemporaryUnavailable, a timeout po wysłaniu żądania w UnknownSubmissionState. Tego ostatniego nie należy traktować jak zwykłego błędu: może wymagać późniejszego sprawdzenia za pomocą klucza idempotencji albo uzgodnienia operacyjnego.
Tłumaczenie błędów nie oznacza usuwania szczegółów. Bezpiecznie rejestruj identyfikator korelacji, przyczynę techniczną i istotną odpowiedź, unikając ujawniania użytkownikowi sekretów lub danych wrażliwych.
Przykład enkapsulacji usługi rezerwacyjnej
Załóżmy, że dostawca wymaga żądania JSON z datami w określonym formacie, własnym kodem hotelu i nagłówkiem autoryzacji. Wewnętrzny przypadek użycia nie powinien tworzyć tego żądania. Otrzymuje wniosek o rezerwację, stosuje własne reguły i wywołuje ReservationGateway.
Adapter ExternalReservationAdapter realizuje konkretne zadania:
- Przekształca wewnętrzny identyfikator obiektu noclegowego w kod rozpoznawany przez dostawcę.
- Formatuje daty, gości i preferencje zgodnie z zewnętrznym kontraktem.
- Dodaje poświadczenia i klucz idempotencji.
- Interpretuje kody HTTP, treści błędów i specyficzne statusy.
- Zwraca wewnętrzną referencję oraz status.
Aplikacja zachowuje regułę określającą, kiedy rezerwacja jest akceptowalna; adapter zachowuje regułę, jak złożyć ją u tego dostawcy. Jeżeli zostanie dodany drugi dostawca, można zaimplementować ten sam port, o ile zdolność biznesowa jest równoważna. Jeśli nie jest, wymuszanie wspólnego interfejsu może ukryć istotne różnice i tworzyć niejednoznaczne decyzje.
Jak wyodrębnić już sprzężoną integrację
Bezpieczna migracja nie wymaga zatrzymania rozwoju produktu. Zacznij od inwentaryzacji: zlokalizuj bezpośrednie wywołania, klasy SDK, formaty zewnętrzne, przepuszczane wyjątki i konsumentów. Najpierw zidentyfikuj ścieżki krytyczne lub te, które zmieniają się najczęściej.
- Wprowadź fasadę: utwórz port i początkowy adapter, który może tymczasowo wykorzystywać część istniejącego klienta.
- Migruj konsumentów według przepływu: zastępuj bezpośrednie wywołania po jednym przypadku użycia naraz. Unikaj utrzymywania dwóch różnych interpretacji tego samego błędu.
- Scentralizuj mapowanie: usuń konwersje zewnętrznych pól i kodów z kontrolerów, usług i szablonów.
- Dodaj obserwowalność: rejestruj opóźnienia, wyniki, znormalizowane błędy oraz korelację między wewnętrznym żądaniem a zewnętrznym wywołaniem.
- Usuń bezpośredni dostęp: gdy nie pozostaną konsumenci, ogranicz lub usuń udostępnionego klienta, aby uniknąć regresji.
W trakcie przejścia fasada nie powinna stać się ogólnym kontenerem metod SDK. Jej celem jest zdefiniowanie użytecznej i stabilnej granicy, a nie przeniesienie sprzężenia do innego katalogu.
Testy i kryteria walidacji izolacji
Testy domeny powinny używać dubli portu. Dzięki temu weryfikują decyzje biznesowe bez sieci, poświadczeń i przypadkowych zachowań dostawcy. Z kolei testy adaptera powinny sprawdzać mapowanie żądań, odpowiedzi i błędów względem kontrolowanego środowiska, symulowanego serwera lub kontraktów udokumentowanych przez system zewnętrzny.
Wynik można zweryfikować, jeśli spełnione są następujące kryteria:
- Zmiana formatu, endpointu lub SDK koncentruje się w adapterze i jego konfiguracji.
- Przypadki użycia zależą od wewnętrznych kontraktów, a nie od klientów HTTP ani typów zewnętrznych.
- Wyjątki i kody dostawcy nie przekraczają granicy.
- Stany niepewne mają jawne traktowanie, w tym idempotencję lub późniejsze sprawdzenie, gdy jest to konieczne.
- Testy biznesowe są uruchamiane z użyciem dubli, a testy integracyjne walidują rzeczywiste tłumaczenie.
Częste błędy przed dodaniem kolejnego dostawcy
Przedwczesna abstrakcja jest ryzykiem: nie twórz złożonej hierarchii dla pojedynczej stabilnej integracji bez rzeczywistych potrzeb zastąpienia. Zawodzi również przeciwne podejście: odtworzenie całego zewnętrznego API w wewnętrznym interfejsie sprawia, że domena dziedziczy jego złożoność.
Przed integracją potwierdź, jakiej zdolności potrzebuje biznes, kto jest właścicielem każdych danych, które błędy umożliwiają działanie, jak unika się duplikacji operacji i co nastąpi, jeśli odpowiedź nie nadejdzie. Zdefiniuj port na podstawie tych decyzji, zaimplementuj adapter jako tłumacza i zachowaj zewnętrzne szczegóły na brzegu. Taka dyscyplina pozwala izolować zewnętrzne integracje w PHP bez przekształcania każdej zmiany dostawcy w przekrojową zmianę aplikacji.
