Znasz to uczucie, gdy zmiana dostawcy p\u0142atno\u015bci w twojej aplikacji oznacza miesi\u0105c refactoringu? Albo gdy nowy regulamin RODO wymusza grzebanie w ca\u0142ym backendzie? W firmach, kt\u00f3re rosn\u0105, takie sytuacje zdarzaj\u0105 si\u0119 regularnie. Problem nie le\u017cy w samej zmianie \u2013 le\u017cy w architekturze, kt\u00f3ra nie zosta\u0142a zaprojektowana z my\u015bl\u0105 o izolacji od zewn\u0119trznych system\u00f3w.<\/p>\n
Architektura hexagonalna (znana te\u017c jako ports and adapters) to podej\u015bcie, kt\u00f3re od lat stosuj\u0105 do\u015bwiadczeni architekci. A mimo to wci\u0105\u017c widz\u0119 projekty, gdzie logika biznesowa jest spl\u0105tana z frameworkiem, baz\u0105 danych czy API zewn\u0119trznym. Efekt? Ka\u017cda zmiana boli, a rozw\u00f3j spowalnia.<\/p>\n
W tym artykule poka\u017c\u0119, jak architektura hexagonalna rozwi\u0105zuje te problemy, ale te\u017c gdzie pope\u0142nia si\u0119 najcz\u0119stsze b\u0142\u0119dy. Nie b\u0119dzie akademickiej teorii \u2013 tylko praktyczne obserwacje z frontu.<\/p>\n
Architektura hexagonalna to wzorzec, kt\u00f3ry separuje logik\u0119 biznesow\u0105 od szczeg\u00f3\u0142\u00f3w technicznych: framework\u00f3w, baz danych, API, system\u00f3w plik\u00f3w. Wyobra\u017a sobie heksagon \u2013 w \u015brodku czysta logika biznesowa (domena), a na zewn\u0105trz porty (interfejsy) i adaptery (implementacje).<\/p>\n
Dzi\u0119ki temu twoja aplikacja nie jest uzale\u017cniona od konkretnego frameworka czy bazy danych. Mo\u017cesz wymieni\u0107 MySQL na PostgreSQL (lub nawet NoSQL) bez dotykania kodu domeny. Mo\u017cesz zmieni\u0107 framework frontendowy, a backend pozostanie nietkni\u0119ty.<\/p>\n
Brzmi jak srebrna kula? Niekoniecznie. Architektura hexagonalna ma swoje koszty: wi\u0119cej plik\u00f3w, wi\u0119cej abstrakcji, wi\u0119cej my\u015blenia. Ale w \u015brednich i du\u017cych projektach zwraca si\u0119 wielokrotnie.<\/p>\n
Cz\u0119sto widz\u0119 porty, kt\u00f3re s\u0105 kopi\u0105 API zewn\u0119trznej biblioteki. Na przyk\u0142ad:<\/p>\n
public interface PaymentGateway {\n PaymentResponse charge(PaymentRequest request);\n RefundResponse refund(RefundRequest request);\n SubscriptionResponse createSubscription(...);\n}\n<\/code><\/pre>\nTo jest b\u0142\u0105d. Port powinien by\u0107 wyrazem potrzeb twojej domeny, a nie lustrem dostawcy. Lepiej:<\/p>\n
public interface PaymentService {\n TransactionId processOrderPayment(Order order);\n void refundOrder(Order order);\n}\n<\/code><\/pre>\nAdapter implementuje to, mapuj\u0105c na specyfik\u0119 Stripe czy PayU. Je\u015bli zmienisz dostawc\u0119, zmieniasz tylko adapter \u2013 port pozostaje ten sam.<\/p>\n
2.2. Brak testowania port\u00f3w<\/h3>\n
Architektura hexagonalna daje mo\u017cliwo\u015b\u0107 testowania logiki biznesowej bez infrastruktury. Wystarcz\u0105 mocki port\u00f3w. Niestety, wiele firm tego nie robi \u2013 testy integracyjne z prawdziw\u0105 baz\u0105 danych s\u0105 powolne i kruche. Efekt? Deweloperzy boj\u0105 si\u0119 refaktoryzowa\u0107, bo testy za d\u0142ugo dzia\u0142aj\u0105.<\/p>\n
Zastosuj testy jednostkowe dla domeny, u\u017cywaj\u0105c in-memory adapter\u00f3w. Na przyk\u0142ad zamiast prawdziwej bazy danych, u\u017cyj repozytorium w pami\u0119ci. To nie tylko szybsze, ale i bardziej przewidywalne.<\/p>\n
2.3. Adaptery jako \u201e\u015bmietnik\u201d<\/h3>\n
Adaptery cz\u0119sto staj\u0105 si\u0119 miejscem, gdzie developerzy wrzucaj\u0105 wszystko, co nie pasuje do domeny. Tymczasem adapter powinien by\u0107 cienki \u2013 tylko mapowanie i delegacja. Je\u015bli w adapterze pojawia si\u0119 logika biznesowa (np. walidacja unikalno\u015bci e-maila), to znak, \u017ce trzeba j\u0105 przenie\u015b\u0107 do domeny.<\/p>\n
3. Realny przypadek z mojego projektu<\/h2>\n
Wsp\u00f3\u0142pracowa\u0142em z firm\u0105 e-commerce, kt\u00f3rej aplikacja monolitowa zacz\u0119\u0142a dusi\u0107 rozw\u00f3j. Ka\u017cda zmiana w koszyku wymaga\u0142a zmian w kontrolerach, serwisach, repozytoriach \u2013 i to w kilku miejscach. Zdecydowali\u015bmy si\u0119 na migracj\u0119 do architektury hexagonalnej krok po kroku.<\/p>\n
Zacz\u0119li\u015bmy od kluczowego modu\u0142u: p\u0142atno\u015bci. Portem sta\u0142 si\u0119 interfejs PaymentService<\/code>, a adapterem implementacja dla Stripe. Po miesi\u0105cu dodali\u015bmy PayPal \u2013 wystarczy\u0142o napisa\u0107 nowy adapter i zmieni\u0107 konfiguracj\u0119. Reszta systemu nie uleg\u0142a zmianie. Po p\u00f3\u0142 roku wymienili\u015bmy ca\u0142\u0105 warstw\u0119 trwa\u0142o\u015bci (z Doctrine na Eloquent) \u2013 dotkn\u0119li\u015bmy tylko adaptery repozytori\u00f3w. Domena zosta\u0142a nietkni\u0119ta.<\/p>\nKoszty? Wi\u0119cej plik\u00f3w, wi\u0119cej interfejs\u00f3w. Ale czas wdro\u017cenia nowych funkcji skr\u00f3ci\u0142 si\u0119 o 40%. A d\u0142ug techniczny przesta\u0142 rosn\u0105\u0107.<\/p>\n
4. Kiedy architektura hexagonalna nie ma sensu?<\/h2>\n
To wa\u017cne: nie ka\u017cdy projekt jej potrzebuje. Je\u015bli robisz prost\u0105 stron\u0119 wizyt\u00f3wk\u0119 lub prototyp MVP, kt\u00f3ry ma sprawdzi\u0107 popyt \u2013 narzucanie heksagonu to przesada. Architektura hexagonalna b\u0142yszczy w \u015brednich i du\u017cych aplikacjach, gdzie zmiany s\u0105 cz\u0119ste, a stabilno\u015b\u0107 kluczowa.<\/p>\n
Dla startup\u00f3w na wczesnym etapie cz\u0119sto lepiej jest pisa\u0107 szybki kod i refaktoryzowa\u0107 p\u00f3\u017aniej. Ale to te\u017c trzeba robi\u0107 m\u0105drze: je\u015bli czujesz, \u017ce logika biznesowa zaczyna miesza\u0107 si\u0119 z frameworkiem, to znak, \u017ce czas na wprowadzenie port\u00f3w i adapter\u00f3w.<\/p>\n
Podsumowanie<\/h2>\n
Architektura hexagonalna to nie moda \u2013 to sprawdzony spos\u00f3b na utrzymanie elastyczno\u015bci w rosn\u0105cych aplikacjach. Nie daj si\u0119 zwie\u015b\u0107 pozornej komplikacji; w d\u0142ugim terminie to inwestycja, kt\u00f3ra zwraca si\u0119 wielokrotnie.<\/p>\n
Je\u015bli twoja aplikacja zaczyna sprawia\u0107 b\u00f3l przy ka\u017cdej zmianie, sp\u00f3jrz na architektur\u0119. Mo\u017ce nie potrzebujesz ca\u0142kowitego przepisania \u2013 wystarczy wyizolowa\u0107 najcz\u0119\u015bciej zmieniaj\u0105ce si\u0119 obszary za pomoc\u0105 port\u00f3w i adapter\u00f3w.<\/p>\n
A je\u015bli potrzebujesz wsparcia w ocenie architektury lub migracji \u2013 w JurskiTech mamy praktyczne do\u015bwiadczenie. Nie sprzedamy ci srebrnej kuli, ale pomo\u017cemy zrozumie\u0107, co naprawd\u0119 warto zmieni\u0107.<\/p>\n","protected":false},"excerpt":{"rendered":"
Wst\u0119p Znasz to uczucie, gdy zmiana dostawcy p\u0142atno\u015bci w twojej aplikacji oznacza miesi\u0105c refactoringu? Albo gdy nowy regulamin RODO wymusza grzebanie w ca\u0142ym backendzie? W firmach, kt\u00f3re rosn\u0105, takie sytuacje zdarzaj\u0105 si\u0119 regularnie. Problem nie le\u017cy w samej zmianie \u2013 le\u017cy w architekturze, kt\u00f3ra nie zosta\u0142a zaprojektowana z my\u015bl\u0105 o izolacji od zewn\u0119trznych system\u00f3w. Architektura<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[52,579,435,24,580],"class_list":["post-1834","post","type-post","status-publish","format-standard","hentry","category-warto-wiedziec","tag-aplikacje-webowe","tag-architektura-hexagonalna","tag-dlug-techniczny","tag-skalowalnosc","tag-utrzymanie-kodu"],"_links":{"self":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/1834","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/comments?post=1834"}],"version-history":[{"count":0,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/1834\/revisions"}],"wp:attachment":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/media?parent=1834"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/categories?post=1834"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/tags?post=1834"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}