Podłączasz urządzenie do komputera albo integrujesz aplikację z obcym API i nagle okazuje się, że oba elementy nie potrafią się ze sobą porozumieć. Jeśli zastanawiasz się, co to jest adapter, najkrócej można powiedzieć, że to łącznik tłumaczący jeden interfejs na drugi. Poniżej pokazuję, jak działa adapter sprzętowy, czym jest wzorzec projektowy Adapter i gdzie w aplikacjach webowych naprawdę ułatwia pracę.
Adapter tłumaczy różne interfejsy i pozwala im współpracować
- Adapter sprzętowy łączy urządzenia o różnych złączach lub standardach.
- Wzorzec Adapter pozwala połączyć kod, którego interfejsy do siebie nie pasują.
- W aplikacji webowej adapter często izoluje zewnętrzne API, bibliotekę albo system płatności.
- Najbezpieczniej budować go przez kompozycję, czyli opakowanie istniejącego obiektu.
- Adapter nie powinien przejmować logiki biznesowej. Jego zadaniem jest głównie mapowanie wywołań i danych.
Adapter łączy rzeczy, które nie mówią tym samym językiem
W codziennym użyciu adapterem nazywamy przejściówkę, która pozwala połączyć dwa urządzenia. Przykładem może być przejściówka z USB-C na HDMI. Z jednej strony mamy konkretny typ złącza, a z drugiej ekran oczekujący innego standardu. Adapter dopasowuje te elementy, ale nie zmienia ich podstawowego przeznaczenia.
W programowaniu idea jest bardzo podobna. Istniejący obiekt, biblioteka lub usługa ma użyteczne funkcje, lecz udostępnia je w formie, której nie oczekuje reszta aplikacji. Adapter staje pomiędzy klientem a niepasującym komponentem i tłumaczy wywołania na właściwy format.
Znaczenie sprzętowe
Adapter sprzętowy może zmieniać rodzaj złącza, sposób przesyłania sygnału albo format komunikacji. Trzeba jednak uważać na częste nieporozumienie. Sama przejściówka mechaniczna nie zawsze konwertuje sygnał, dlatego urządzenie może nadal nie działać, jeśli wymagany jest aktywny konwerter lub obsługa konkretnego standardu.
Znaczenie programistyczne
W architekturze oprogramowania adapter jest warstwą pośrednią. Dzięki niej kod korzystający z usługi nie musi znać jej oryginalnego interfejsu. To szczególnie przydatne przy integracji starego kodu, zewnętrznych bibliotek i usług dostawców, których nie chcemy rozprowadzać po całej aplikacji.
Jak działa wzorzec Adapter w programowaniu
Wzorzec Adapter zalicza się do strukturalnych wzorców projektowych. Nie tworzy nowych funkcji biznesowych. Porządkuje sposób, w jaki istniejące elementy komunikują się ze sobą, gdy ich kontrakty są niezgodne.
Najczęściej występują w nim cztery role:
- Klient korzysta z oczekiwanego interfejsu.
- Interfejs docelowy opisuje metody, których potrzebuje klient.
- Adaptee to istniejąca klasa, biblioteka lub usługa z innym interfejsem.
- Adapter implementuje oczekiwany interfejs i deleguje pracę do adaptee.
Załóżmy, że aplikacja oczekuje metody getTemperature(), ale używana biblioteka udostępnia tylko fetchWeatherData() i zwraca dane w innym formacie. Adapter wywoła obcą metodę, odczyta wynik i zwróci go zgodnie z kontraktem aplikacji.
interface WeatherProvider {
getTemperature(city: string): Promise;
}
class LegacyWeatherApi {
async fetchWeatherData(city: string) {
return { temp_c: 21 };
}
}
class WeatherAdapter implements WeatherProvider {
constructor(private api: LegacyWeatherApi) {}
async getTemperature(city: string): Promise {
const data = await this.api.fetchWeatherData(city);
return Number(data.temp_c);
}
} Kod korzystający z WeatherProvider nie musi wiedzieć, że pod spodem działa starsze API. To właśnie największa korzyść tego wzorca: zmiana dostawcy nie musi oznaczać przebudowy całej aplikacji.
Kompozycja czy dziedziczenie
W praktyce częściej wybieram adapter oparty na kompozycji. Adapter otrzymuje obiekt zależności w konstruktorze i przekazuje mu zadania. Takie rozwiązanie łatwiej testować, podmieniać i rozwijać niż klasę silnie związaną z hierarchią dziedziczenia.
Adapter klasowy oparty na dziedziczeniu może być użyteczny w niektórych językach, ale zwykle zwiększa zależności. Gdy zewnętrzna biblioteka zmieni strukturę, adapter dziedziczący po jej klasie może wymagać większych modyfikacji.
Gdzie adapter przydaje się w aplikacji webowej
Najwięcej wartości daje na granicach systemu, czyli tam, gdzie aplikacja styka się z czymś zewnętrznym. W architekturze heksagonalnej mówi się o portach i adapterach. Port opisuje, czego potrzebuje domena, a adapter dostarcza konkretną implementację dla bazy danych, API lub dostawcy płatności.
Integracja z zewnętrznym API
Załóżmy, że sklep korzysta z dostawcy płatności. Zamiast wywoływać jego SDK bezpośrednio w kontrolerach, można zdefiniować własny interfejs PaymentGateway. Adapter zamieni go na wymagania konkretnego operatora, a reszta aplikacji pozostanie niezależna od nazw metod i formatów używanych przez dostawcę.
To rozwiązanie ułatwia także zmianę operatora. Nie eliminuje kosztu migracji, ale ogranicza go do jednej warstwy, mapowania konfiguracji i testów integracyjnych.
Stara biblioteka albo kod legacy
W wielu projektach nie opłaca się od razu przepisywać działającego modułu. Adapter pozwala używać starego komponentu przez nowy, czytelniejszy interfejs. Sam traktuję to jako rozsądny etap przejściowy, pod warunkiem że adapter nie zaczyna ukrywać dziesiątek wyjątków i niejasnych reguł.
Przeczytaj również: SOLID w aplikacjach webowych - Czy naprawdę go potrzebujesz?
Warstwa danych i systemy zewnętrzne
Adapter może tłumaczyć rekord z bazy danych na obiekt domenowy albo odpowiedź z zewnętrznego API na model używany przez frontend. Dzięki temu typy dostawcy nie przeciekają do całej aplikacji. Granica systemu pozostaje wyraźna, a wymiana technologii jest mniej bolesna.
Adapter, wrapper, fasada i bridge nie znaczą tego samego
Te pojęcia bywają używane zamiennie, ale opisują różne problemy. Wszystkie mogą obejmować obiekt opakowujący inną klasę, jednak ich cel jest inny.
| Rozwiązanie | Główny cel | Przykład |
|---|---|---|
| Adapter | Dopasowanie niezgodnych interfejsów | Własny interfejs płatności dla obcego SDK |
| Wrapper | Ogólne opakowanie obiektu | Klasa przekazująca wywołania do innej klasy |
| Fasada | Uproszczenie dostępu do kilku komponentów | Jedna metoda uruchamiająca cały proces zamówienia |
| Bridge | Oddzielenie abstrakcji od implementacji | Wymienne implementacje zapisu danych |
Najprostszy test jest praktyczny. Jeśli klient oczekuje jednego interfejsu, a istniejący komponent oferuje inny, prawdopodobnie potrzebujesz adaptera. Jeśli chcesz tylko uprościć wiele operacji albo dodać zachowanie przed wywołaniem, bliżej temu do fasady lub dekoratora.
Najważniejsze zalety i pułapki stosowania adaptera
Dobrze zaprojektowany adapter zmniejsza zależność od dostawcy, ułatwia testowanie i pozwala wymieniać komponenty bez zmian w logice domenowej. Szczególnie cenię go wtedy, gdy integracja jest niestabilna albo istnieje realna szansa zmiany biblioteki w przyszłości.
- Izoluje zmiany w zewnętrznym API.
- Ułatwia tworzenie mocków i testów jednostkowych.
- Porządkuje konwersję danych i błędów.
- Pomaga stopniowo modernizować kod legacy.
Nie jest to jednak magiczna warstwa, która naprawi każdą architekturę. Zbyt rozbudowany adapter może stać się drugim systemem biznesowym, a wtedy trudniej zrozumieć, gdzie naprawdę znajduje się logika.
Najczęstszy błąd polega na przepuszczaniu przez adapter typów dostawcy. Jeżeli domena zaczyna używać klas konkretnego SDK, izolacja przestaje działać. Lepiej mapować dane na własne modele i tłumaczyć także błędy, statusy oraz ograniczenia usługi.
Jak zaprojektować adapter, który nie utrudni rozwoju
- Zdefiniuj docelowy kontrakt. Najpierw opisz, czego naprawdę potrzebuje aplikacja, zamiast kopiować interfejs zewnętrznej biblioteki.
- Umieść obcą zależność na brzegu systemu. Kontroler, klient API lub repozytorium może korzystać z adaptera, ale logika domenowa powinna znać tylko własny port.
- Mapuj dane jawnie. Nie przekazuj bezpośrednio obiektów z SDK. Przekształć je w modele używane w aplikacji.
- Ustal zachowanie przy błędach. Adapter powinien zamieniać techniczne wyjątki dostawcy na błędy zrozumiałe dla reszty systemu.
- Dodaj test kontraktowy i integracyjny. Test jednostkowy sprawdzi mapowanie, a integracyjny potwierdzi, że adapter faktycznie rozmawia z usługą.
Warto też pilnować zakresu odpowiedzialności. Adapter może normalizować format daty, nazwy pól czy kody błędów, ale nie powinien decydować, czy klient otrzyma rabat. Reguły biznesowe zostawiam warstwie domenowej, bo wtedy adapter pozostaje prosty i wymienny.
Po czym poznać, że adapter jest tu właściwym rozwiązaniem
Zadaję sobie trzy pytania. Czy istniejący komponent jest użyteczny, ale ma niepasujący interfejs? Czy chcę odizolować aplikację od konkretnego dostawcy? Czy konwersja danych i błędów ma jedno wyraźne miejsce? Jeśli odpowiedź brzmi „tak”, adapter prawdopodobnie rozwiąże realny problem.
Jeżeli natomiast tworzysz tylko jedną krótką funkcję mapującą i nie ma obcej zależności, osobna klasa może być przesadą. Dobry adapter nie zwiększa liczby warstw dla samej elegancji. Ma sprawić, że reszta kodu nie musi wiedzieć, jak działa zewnętrzny świat, a właśnie to jest jego największą wartością.
