• Backend i API
  • Clean Architecture w API - gdzie umieścić logikę biznesową?

Clean Architecture w API - gdzie umieścić logikę biznesową?

1 listopada 2026

Warstwy Clean Architecture: Interfejs użytkownika, Infrastruktura i Rdzeń aplikacji. Testy są opcjonalne.

Endpoint POST /orders działa, ale po zmianie bazy danych trzeba poprawiać kontroler, walidację i testy, a reguła rabatowa jest schowana w zapytaniu SQL. Clean architecture zwykle ogranicza takie sprzężenie, kierując zależności kodu do wnętrza aplikacji, choć sam podział na warstwy nie wystarczy, jeśli logika biznesowa nadal przecieka do API.

Schemat warstwowy ilustrujący zasady clean architecture. Moduły z implementacją i abstrakcją, zależność między warstwami.

Reguły biznesowe powinny przetrwać zmianę bazy i frameworka

  • Reguła zależności: kod domeny nie importuje kontrolerów, ORM-u ani klienta zewnętrznego API.
  • Przepływ żądania: kontroler przekazuje dane do przypadku użycia, a adapter infrastruktury realizuje zapis lub odczyt.
  • Granica opłacalności: osobne warstwy pomagają, gdy logika i integracje rosną; dla prostego CRUD-u mogą być zbędnym narzutem.
  • Testy: reguły biznesowe da się sprawdzić bez uruchamiania serwera HTTP i prawdziwej bazy.

Najważniejszy test brzmi: czy domena zna szczegóły techniczne?

W praktyce czystość architektury widać po kierunku importów, nie po liczbie folderów. Jeśli obiekt zamówienia odwołuje się do typu z Entity Framework albo przypadek użycia czyta nagłówek HTTP, szczegóły zewnętrzne wdarły się do środka.

Reguła zależności mówi, że kod zewnętrznych warstw może korzystać z kodu wewnętrznych, ale nie odwrotnie. Według Microsoft Learn, interfejsy potrzebne do dostępu do infrastruktury mogą być zdefiniowane w rdzeniu aplikacji, a ich implementacje umieszczone na zewnątrz. To pozwala domenie opisać potrzebę, nie wskazując konkretnej bazy.

W API oznacza to, że kontroler zna format żądania i odpowiedzi, ale nie podejmuje decyzji o cenie, uprawnieniach czy dostępności produktu. Te decyzje należą do przypadku użycia lub modelu domenowego. Kontroler ma tłumaczyć HTTP na język aplikacji, a nie stawać się miejscem, w którym mieszka cała logika.

Jedno żądanie zamówienia pokazuje, gdzie umieścić każdą odpowiedzialność

Wyobraź sobie endpoint, który przyjmuje identyfikator produktu i liczbę sztuk. W prostym projekcie łatwo umieścić wszystko w kontrolerze, ale wtedy walidacja biznesowa miesza się z kodem HTTP, a zapis z detalami bazy.

W podejściu warstwowym przepływ może wyglądać tak: kontroler tworzy komendę, przypadek użycia sprawdza reguły i wywołuje port repozytorium, a adapter infrastruktury zapisuje dane. Port to interfejs opisujący potrzebną operację; adapter to konkretna implementacja, na przykład repozytorium oparte na PostgreSQL.

Sytuacja w kodzie Prawdopodobny skutek Co zrobić
Kontroler sam wylicza rabat Reguła może zostać pominięta przez inne wejście, np. zadanie w tle Przenieś decyzję do przypadku użycia lub domeny
Przypadek użycia zwraca encję ORM Model bazy zaczyna dyktować kontrakt API Zwróć DTO aplikacyjne, a odpowiedź HTTP zbuduj w warstwie API
Domena importuje klienta płatności Test reguły wymaga konfiguracji zewnętrznej integracji Zdefiniuj port płatności wewnątrz, implementację umieść na zewnątrz
Repozytorium zawiera regułę „nie można zamknąć opłaconego zamówienia” Reguła biznesowa zostaje ukryta w dostępie do danych Przenieś ją do domeny, a repozytorium pozostaw odczytowi i zapisowi

Odpowiedź HTTP, na przykład 201 Created albo 409 Conflict, należy do adaptera wejściowego. Aplikacja może zwrócić wynik operacji lub błąd domenowy, a kontroler mapuje go na status i reprezentację API. Dzięki temu ten sam przypadek użycia może obsłużyć HTTP, kolejkę albo zadanie cykliczne, o ile takie wejścia rzeczywiście są potrzebne.

Osobne warstwy opłacają się dopiero przy określonej złożoności

Można zbudować czysty projekt z wieloma bibliotekami, interfejsami i mapperami, a mimo to utrudnić każdą zmianę. Prawdę mówiąc, sama liczba warstw nie jest dobrym miernikiem jakości. Ważniejsze, czy separacja chroni reguły, które często się zmieniają albo są współdzielone przez różne wejścia.

Praktyczna reguła

decyzji jest prosta: jeśli endpoint wykonuje głównie walidację składni i zapis prostych danych, zacznij od mniejszej struktury; jeśli obejmuje kilka reguł, autoryzację zasobów, transakcję lub integrację zewnętrzną, wydziel przypadek użycia i granice zależności. Nie trzeba od razu tworzyć osobnego projektu dla każdej warstwy. Moduły i pakiety wystarczą, dopóki nie ma powodu do mocniejszej izolacji.

W dokumentacji Microsoft Learn o aplikacjach ASP.NET Core architektura Clean Architecture jest przedstawiona jako sposób organizacji kodu z oddzielonym rdzeniem, interfejsem użytkownika i infrastrukturą. To przykład, nie nakaz kopiowania układu projektów do każdego stosu technologicznego. Przenoś zasady, niekoniecznie strukturę katalogów.

Clean Architecture nie wymaga repozytorium dla każdej tabeli

Częsty skrót myślowy brzmi: „czysta architektura oznacza interfejs repozytorium dla wszystkiego”. Tymczasem abstrakcja ma sens wtedy, gdy chroni granicę lub oddziela politykę biznesową od szczegółu zapisu. Jeśli interfejs tylko powtarza metody ORM-u i nie wnosi takiej ochrony, dodaje pośrednią warstwę bez realnej korzyści.

Podobnie DTO nie powinno automatycznie powstawać dla każdego obiektu w każdej warstwie. Osobny model wejściowy API jest przydatny, gdy kontrakt HTTP ma być stabilny mimo zmian domeny; model wyniku przypadku użycia pomaga, gdy z tego samego procesu korzysta więcej niż jeden adapter. Wydzielaj model wtedy, gdy oddziela dwie różne odpowiedzialności, nie dla samego mnożenia typów.

Robert C. Martin opisuje tę ideę jako Dependency Rule: szczegóły, takie jak interfejs użytkownika czy baza, nie powinny dyktować kodu wysokopoziomowym regułom. Uważam, że to trafniejszy sprawdzian niż pytanie, czy projekt ma „właściwą” liczbę warstw.

Testuj granice, a nie samą obecność interfejsów

Test jednostkowy przypadku użycia może podstawić atrapę portu repozytorium i sprawdzić, czy zamówienie z niedozwoloną liczbą sztuk zostaje odrzucone. Taki test nie potwierdza jeszcze, że adapter bazy poprawnie zapisuje dane, więc potrzebny jest też test integracyjny dla połączenia z prawdziwym mechanizmem persystencji.

Przydatny podział wygląda następująco:

  • Testy domeny sprawdzają reguły i nie uruchamiają API ani bazy.
  • Testy przypadków użycia weryfikują przepływ decyzji przy podmienionych portach.
  • Testy integracyjne sprawdzają adaptery, mapowanie danych i konfigurację infrastruktury.
  • Testy kontraktowe API pilnują, by odpowiedzi HTTP nie zmieniły się przypadkiem przy refaktorze wewnętrznym.

Jeśli test każdej drobnej metody wymaga rozbudowanej konfiguracji atrap, problemem może być nadmierne rozdrobnienie projektu albo przeciek zależności, a nie brak kolejnego interfejsu. Testowalność wynika z sensownych granic, nie z samego użycia dependency injection.

Zacznij od granicy, która najczęściej pęka

Gdy endpoint staje się trudny w zmianie, prześledź jedno żądanie od kontrolera do bazy i zaznacz miejsca, w których reguły biznesowe dotykają HTTP, ORM-u lub usług zewnętrznych. Najpierw odseparuj tę jedną regułę i sprawdź ją bez infrastruktury. Tak powstaje użyteczna architektura: nie z diagramu skopiowanego do projektu, lecz z granic, które pozwalają zmieniać techniczne szczegóły bez przepisywania zachowania API.

FAQ - Najczęstsze pytania

Kontroler tłumaczy żądanie HTTP na komendę i przekazuje ją do przypadku użycia. Przypadek użycia sprawdza reguły biznesowe oraz korzysta z portu repozytorium, a adapter infrastruktury wykonuje zapis, na przykład w PostgreSQL. Na końcu kontroler mapuje wynik lub błąd domenowy na odpowiedź HTTP, taką jak 201 Created albo 409 Conflict.

Takie decyzje powinny znajdować się w przypadku użycia lub modelu domenowym, a nie w kontrolerze, repozytorium ani zapytaniu SQL. Dzięki temu reguła rabatowa obowiązuje także przy obsłudze zamówienia z kolejki lub zadania cyklicznego, a regułę zamówienia można testować bez uruchamiania bazy.

Jeśli endpoint wykonuje głównie walidację składni i zapis prostych danych, mniejsza struktura może być wystarczająca. Przypadek użycia i wyraźne granice zależności warto wydzielić, gdy pojawiają się liczne reguły, autoryzacja zasobów, transakcje albo integracje zewnętrzne. Clean Architecture nie wymaga też tworzenia repozytorium dla każdej tabeli, jeśli interfejs tylko powiela metody ORM-u.

Testy domeny sprawdzają reguły bez API i bazy, a testy przypadków użycia korzystają z podmienionych portów, na przykład atrapy repozytorium. Adaptery i mapowanie danych należy sprawdzać testami integracyjnymi, natomiast testy kontraktowe API pilnują stabilności odpowiedzi HTTP podczas zmian wewnętrznych.
Oceń artykuł

Średnia: 4.3 / 5 · 4 oceny

Tagi

przypadki użycia repozytoria testy integracyjne czysta architektura reguła zależności

Udostępnij artykuł

Komentarze (0)
Dodaj komentarz