Clean Architecture — wprowadzenie w 5 minut

Clean Architecture to koncepcja Roberta C. Martina (“Uncle Bob”) odpowiadająca na jedno pytanie: jak zorganizować kod, żeby zmiana bazy danych, frameworka albo UI nie wymagała przepisywania logiki biznesowej? Odpowiedź: podziel system na warstwy i pilnuj, w którą stronę mogą wskazywać zależności między nimi.

Cztery warstwy

1. Domain — najważniejsze reguły biznesowe. Serce systemu, zero zależności od czegokolwiek innego.
2. Application — przypadki użycia (use case’y), koordynuje pracę warstwy Domain.
3. Infrastructure — szczegóły techniczne: baza danych, zewnętrzne API, system plików.
4. UI / API — prezentacja danych i obsługa żądań użytkownika (kontroler, strona, CLI).

Reguła zależności — najważniejsza zasada całej architektury

Zależności mogą wskazywać tylko do wewnątrz. Domain nie wie nic o Infrastructure ani UI. Infrastructure zależy od Domain — nigdy odwrotnie.

// Domain — interfejs, ZERO wzmianki o SQL, EF Core czy jakiejkolwiek bazie
namespace Domain;
public interface IZamowienieRepository
{
    void Zapisz(Zamowienie zamowienie);
}

// Infrastructure — implementacja ZALEŻY od Domain, nie odwrotnie
namespace Infrastructure;
public class SqlZamowienieRepository : Domain.IZamowienieRepository
{
    public void Zapisz(Zamowienie zamowienie)
    {
        // konkretny kod SQL/EF Core — szczegół, który można podmienić
    }
}

Domain deklaruje interfejs, Infrastructure go implementuje — strzałka zależności (Infrastructure → Domain) wskazuje do środka. Gdybyś jutro zamienił SQL Server na MongoDB, napiszesz nową klasę w Infrastructure — Domain nie zauważy różnicy, bo nigdy nie znał szczegółów implementacji.

Najczęstsze złamanie reguły

// ❌ Domain z atrybutami Entity Framework — Domain "wie" o bazie danych
namespace Domain;

[Table("Zamowienia")] // ❌ szczegół Infrastructure wyciekł do Domain
public class Zamowienie
{
    [Key] public int Id { get; set; }
}

Atrybuty EF Core ([Table], [Key]) to konfiguracja bazy danych — jeśli pojawiają się bezpośrednio na klasach w Domain, warstwa, która miała być “czysta” od szczegółów technicznych, zaczyna o nich wiedzieć. Rozwiązanie: konfiguracja mapowania EF Core (Fluent API) żyje w Infrastructure, nie jako atrybuty na encji domenowej.

Dlaczego to się opłaca

• Testowalność — logikę w Domain i Application testujesz bez bazy danych, bez serwera, bez mocków infrastruktury.
• Wymienność szczegółów — baza danych, framework webowy, dostawca e-maili to detale, które można podmienić bez ruszania reguł biznesowych.
• Czytelność intencji — patrząc na Domain, widzisz co system robi, nie jak jest zaimplementowany technicznie.

Cena tej struktury

Więcej projektów/folderów, więcej interfejsów, więcej pośredniej abstrakcji niż w prostym CRUD-zie. Dla małej aplikacji bez planów rozwoju to koszt bez korzyści — YAGNI dotyczy też architektury, nie tylko pojedynczych funkcji.

Co dalej

To był obraz w pigułce. Dwa naturalne kolejne kroki:

• Czysta architektura: fundamenty elastycznych systemów — głębiej w zasady stojące za regułą zależności.
• Clean Architecture w .NET 10 — refaktoryzacja krok po kroku — pełna, praktyczna refaktoryzacja prawdziwego kontrolera do tej struktury, z testami.

Podsumowanie

Clean Architecture to reguła zależności egzekwowana przez podział na warstwy: Domain w centrum, bez żadnych zależności na zewnątrz; Infrastructure i UI na zewnątrz, zależne od Domain, nigdy odwrotnie. To narzędzie do zarządzania złożonością rosnących systemów — nie każdy projekt go potrzebuje, ale gdy go potrzebujesz, ta jedna zasada (kierunek strzałek zależności) wyjaśnia niemal wszystko inne.