Wstęp
Znasz to uczucie, gdy zmiana dostawcy płatności w twojej aplikacji oznacza miesiąc refactoringu? Albo gdy nowy regulamin RODO wymusza grzebanie w całym backendzie? W firmach, które rosną, takie sytuacje zdarzają się regularnie. Problem nie leży w samej zmianie – leży w architekturze, która nie została zaprojektowana z myślą o izolacji od zewnętrznych systemów.
Architektura hexagonalna (znana też jako ports and adapters) to podejście, które od lat stosują doświadczeni architekci. A mimo to wciąż widzę projekty, gdzie logika biznesowa jest splątana z frameworkiem, bazą danych czy API zewnętrznym. Efekt? Każda zmiana boli, a rozwój spowalnia.
W tym artykule pokażę, jak architektura hexagonalna rozwiązuje te problemy, ale też gdzie popełnia się najczęstsze błędy. Nie będzie akademickiej teorii – tylko praktyczne obserwacje z frontu.
1. Czym jest architektura hexagonalna (w 5 minut)
Architektura hexagonalna to wzorzec, który separuje logikę biznesową od szczegółów technicznych: frameworków, baz danych, API, systemów plików. Wyobraź sobie heksagon – w środku czysta logika biznesowa (domena), a na zewnątrz porty (interfejsy) i adaptery (implementacje).
Dzięki temu twoja aplikacja nie jest uzależniona od konkretnego frameworka czy bazy danych. Możesz wymienić MySQL na PostgreSQL (lub nawet NoSQL) bez dotykania kodu domeny. Możesz zmienić framework frontendowy, a backend pozostanie nietknięty.
Brzmi jak srebrna kula? Niekoniecznie. Architektura hexagonalna ma swoje koszty: więcej plików, więcej abstrakcji, więcej myślenia. Ale w średnich i dużych projektach zwraca się wielokrotnie.
2. Gdzie firmy najczęściej popełniają błędy?
2.1. Porty zbyt szczegółowe
Często widzę porty, które są kopią API zewnętrznej biblioteki. Na przykład:
public interface PaymentGateway {
PaymentResponse charge(PaymentRequest request);
RefundResponse refund(RefundRequest request);
SubscriptionResponse createSubscription(...);
}
To jest błąd. Port powinien być wyrazem potrzeb twojej domeny, a nie lustrem dostawcy. Lepiej:
public interface PaymentService {
TransactionId processOrderPayment(Order order);
void refundOrder(Order order);
}
Adapter implementuje to, mapując na specyfikę Stripe czy PayU. Jeśli zmienisz dostawcę, zmieniasz tylko adapter – port pozostaje ten sam.
2.2. Brak testowania portów
Architektura hexagonalna daje możliwość testowania logiki biznesowej bez infrastruktury. Wystarczą mocki portów. Niestety, wiele firm tego nie robi – testy integracyjne z prawdziwą bazą danych są powolne i kruche. Efekt? Deweloperzy boją się refaktoryzować, bo testy za długo działają.
Zastosuj testy jednostkowe dla domeny, używając in-memory adapterów. Na przykład zamiast prawdziwej bazy danych, użyj repozytorium w pamięci. To nie tylko szybsze, ale i bardziej przewidywalne.
2.3. Adaptery jako „śmietnik”
Adaptery często stają się miejscem, gdzie developerzy wrzucają wszystko, co nie pasuje do domeny. Tymczasem adapter powinien być cienki – tylko mapowanie i delegacja. Jeśli w adapterze pojawia się logika biznesowa (np. walidacja unikalności e-maila), to znak, że trzeba ją przenieść do domeny.
3. Realny przypadek z mojego projektu
Współpracowałem z firmą e-commerce, której aplikacja monolitowa zaczęła dusić rozwój. Każda zmiana w koszyku wymagała zmian w kontrolerach, serwisach, repozytoriach – i to w kilku miejscach. Zdecydowaliśmy się na migrację do architektury hexagonalnej krok po kroku.
Zaczęliśmy od kluczowego modułu: płatności. Portem stał się interfejs PaymentService, a adapterem implementacja dla Stripe. Po miesiącu dodaliśmy PayPal – wystarczyło napisać nowy adapter i zmienić konfigurację. Reszta systemu nie uległa zmianie. Po pół roku wymieniliśmy całą warstwę trwałości (z Doctrine na Eloquent) – dotknęliśmy tylko adaptery repozytoriów. Domena została nietknięta.
Koszty? Więcej plików, więcej interfejsów. Ale czas wdrożenia nowych funkcji skrócił się o 40%. A dług techniczny przestał rosnąć.
4. Kiedy architektura hexagonalna nie ma sensu?
To ważne: nie każdy projekt jej potrzebuje. Jeśli robisz prostą stronę wizytówkę lub prototyp MVP, który ma sprawdzić popyt – narzucanie heksagonu to przesada. Architektura hexagonalna błyszczy w średnich i dużych aplikacjach, gdzie zmiany są częste, a stabilność kluczowa.
Dla startupów na wczesnym etapie często lepiej jest pisać szybki kod i refaktoryzować później. Ale to też trzeba robić mądrze: jeśli czujesz, że logika biznesowa zaczyna mieszać się z frameworkiem, to znak, że czas na wprowadzenie portów i adapterów.
Podsumowanie
Architektura hexagonalna to nie moda – to sprawdzony sposób na utrzymanie elastyczności w rosnących aplikacjach. Nie daj się zwieść pozornej komplikacji; w długim terminie to inwestycja, która zwraca się wielokrotnie.
Jeśli twoja aplikacja zaczyna sprawiać ból przy każdej zmianie, spójrz na architekturę. Może nie potrzebujesz całkowitego przepisania – wystarczy wyizolować najczęściej zmieniające się obszary za pomocą portów i adapterów.
A jeśli potrzebujesz wsparcia w ocenie architektury lub migracji – w JurskiTech mamy praktyczne doświadczenie. Nie sprzedamy ci srebrnej kuli, ale pomożemy zrozumieć, co naprawdę warto zmienić.
