Clean Architecture - architektura niezależna od frameworków i bazy danych
Co to jest i skąd się wzięła
Clean Architecture to styl organizacji kodu opisany przez Roberta C. Martina ("Uncle Bob") na blogu w 2012 roku i rozwinięty w książce z 2017. Nie jest to zupełnie nowy pomysł - to synteza kilku wcześniejszych podejść, które łączy wspólny cel:
- Hexagonal Architecture (Ports and Adapters, Alistair Cockburn, 2005),
- Onion Architecture (Jeffrey Palermo, 2008),
- BCE / DCI i inne architektury skupione na logice biznesowej.
Wspólna idea: logika biznesowa jest sercem aplikacji i nie może zależeć od szczegółów technicznych - bazy danych, frameworka webowego, UI, zewnętrznych API. To szczegóły mają zależeć od logiki, a nie odwrotnie.
Co to daje w praktyce:
- Testowalność - logikę biznesową można testować bez bazy, bez serwera HTTP, bez kontenera DI,
- Wymienialność szczegółów - zmiana EF Core na Dapper albo SQL Server na PostgreSQL dotyka jednej warstwy, nie całej aplikacji,
- Odroczone decyzje - można zacząć pisać logikę, zanim zdecyduje się o bazie czy UI,
- Długowieczność - framework się zestarzeje (WinForms, WCF, ASP.NET MVC 5), a reguły biznesowe zostają.
Reguła zależności (Dependency Rule)
To jest jedyna naprawdę kluczowa zasada całego podejścia. Architekturę rysuje się jako koncentryczne kręgi:
┌─────────────────────────────────────────────────────────┐
│ Frameworks & Drivers (Web, UI, DB, zewnętrzne API) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Interface Adapters (kontrolery, repozytoria) │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Use Cases (logika aplikacji) │ │ │
│ │ │ ┌───────────────────────────────────────┐ │ │ │
│ │ │ │ Entities (reguły biznesowe) │ │ │ │
│ │ │ └───────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Zależności kodu źródłowego wskazują ZAWSZE do środka
Zależności w kodzie źródłowym mogą wskazywać tylko do wewnątrz. Wewnętrzny krąg nie wie nic o istnieniu zewnętrznego - nie importuje jego klas, nie używa jego nazw, nie zna jego typów.
| Krąg | Co zawiera | Przykład w .NET |
|---|---|---|
| Entities | Reguły biznesowe całej firmy, obiekty domenowe | Order, Customer, Money, wyjątki domenowe |
| Use Cases | Reguły specyficzne dla aplikacji, scenariusze użycia | Handlery komend/zapytań, interfejsy repozytoriów |
| Interface Adapters | Konwersja danych między use case'ami a światem zewnętrznym | Kontrolery, presentery, implementacje repozytoriów |
| Frameworks & Drivers | Szczegóły techniczne | ASP.NET Core, EF Core, SQL Server, RabbitMQ, system plików |
Jak to możliwe, skoro Use Case musi zapisać dane do bazy?
Tu wchodzi Dependency Inversion Principle z SOLID (omówiony na początku tej strony). Przepływ sterowania idzie "na zewnątrz" (handler woła bazę), ale zależność w kodzie jest odwrócona:
Przepływ sterowania: Handler ───────────────► Baza danych
Zależności w kodzie: Handler ──► IOrderRepository ◄── OrderRepository (EF Core)
(Application) (Application) (Infrastructure)
Interfejs IOrderRepository należy do warstwy wewnętrznej (Application) - to ona dyktuje, czego potrzebuje. Implementacja z EF Core żyje na zewnątrz i zależy od interfejsu, nie na odwrót. To właśnie to samo, co robi kontener DI przy Inversion of Control.
Mapowanie na solution w .NET
W praktyce kręgi zamienia się na 4 projekty (assembly) w jednym solution. Referencje między projektami wymuszają regułę zależności już na poziomie kompilatora:
Shop.sln
├── Shop.Domain ← Entities (zero referencji do innych projektów)
├── Shop.Application ← Use Cases (referencja: Domain)
├── Shop.Infrastructure ← EF Core, zewnętrzne serwisy (referencje: Application, Domain)
└── Shop.WebApi ← Presentation + Composition Root (referencje: Application, Infrastructure)
WebApi ─────────┬──────────► Application ──────► Domain
│ │ ▲
└────────► Infrastructure ─────┘
(tylko do rejestracji DI)
| Projekt | Zawartość | Czego tu NIE ma |
|---|---|---|
| Domain | Encje, value objects, enumy, wyjątki domenowe, zdarzenia domenowe | EF Core, ASP.NET, JSON, jakiekolwiek NuGet "techniczne" |
| Application | Komendy/zapytania i handlery, interfejsy (IOrderRepository, IEmailSender, IUnitOfWork), DTO, walidatory, mapowania |
Implementacje dostępu do danych, kontrolery, DbContext |
| Infrastructure | DbContext, konfiguracje EF, repozytoria, klienci HTTP, implementacje IEmailSender, Kafka/RabbitMQ |
Logika biznesowa |
| WebApi | Kontrolery / minimal API, middleware, Program.cs (Composition Root) |
Logika biznesowa, bezpośrednie użycie DbContext |
Warstwa WebApi jest jedyną, która "widzi wszystko" - bo to ona składa aplikację w całość (Composition Root), rejestrując implementacje w kontenerze DI. Nigdzie indziej nie wolno tworzyć konkretnych klas infrastruktury.
Pełny przykład - tworzenie zamówienia
Domain - encja z regułami biznesowymi
namespace Shop.Domain.Orders;
public class Order
{
private readonly List<OrderItem> _items = new();
public int Id { get; private set; }
public string CustomerName { get; private set; } = default!;
public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
public decimal TotalAmount => _items.Sum(i => i.UnitPrice * i.Quantity);
private Order() { } // wymagany przez EF Core, ale nie "przecieka" do reszty kodu
public Order(string customerName)
{
if (string.IsNullOrWhiteSpace(customerName))
throw new DomainException("Nazwa klienta jest wymagana.");
CustomerName = customerName;
}
// Reguły biznesowe żyją W encji, a nie w serwisie czy kontrolerze
public void AddItem(string productName, decimal unitPrice, int quantity)
{
if (quantity <= 0)
throw new DomainException("Ilość musi być większa od zera.");
_items.Add(new OrderItem(productName, unitPrice, quantity));
}
}
To jest korzeń agregatu (więcej w sekcji "Agregaty" niżej). Zwróć uwagę: żadnego using Microsoft.EntityFrameworkCore, żadnych atrybutów [Key]/[Table]. Konfiguracja mapowania jest w Infrastructure (Fluent API). Encja ma prywatne settery i chroni swoje niezmienniki - to nie jest "worek na dane" (anemic model).
Application - interfejsy (porty) i use case
namespace Shop.Application.Orders;
// PORT - to Application mówi, czego potrzebuje; nie wie nic o EF Core
public interface IOrderRepository
{
Task AddAsync(Order order, CancellationToken ct);
Task<Order?> GetByIdAsync(int id, CancellationToken ct);
}
public interface IUnitOfWork
{
Task<int> SaveChangesAsync(CancellationToken ct);
}
public record OrderItemDto(string ProductName, decimal UnitPrice, int Quantity);
public record CreateOrderCommand(string CustomerName, List<OrderItemDto> Items) : IRequest<int>;
public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, int>
{
private readonly IOrderRepository _orders;
private readonly IUnitOfWork _unitOfWork;
public CreateOrderHandler(IOrderRepository orders, IUnitOfWork unitOfWork)
{
_orders = orders;
_unitOfWork = unitOfWork;
}
public async Task<int> Handle(CreateOrderCommand command, CancellationToken ct)
{
var order = new Order(command.CustomerName);
foreach (var item in command.Items)
order.AddItem(item.ProductName, item.UnitPrice, item.Quantity);
await _orders.AddAsync(order, ct);
await _unitOfWork.SaveChangesAsync(ct);
return order.Id;
}
}
To jest klasyczny Use Case - orkiestruje scenariusz (utwórz, dodaj pozycje, zapisz), ale same reguły biznesowe zostają w encji. Handler korzysta z MediatR (patrz MediatR - jak działa i jak używać), choć sama Clean Architecture MediatR nie wymaga - to tylko wygodny sposób na realizację use case'ów.
Infrastructure - szczegóły techniczne
namespace Shop.Infrastructure.Persistence;
public class AppDbContext : DbContext, IUnitOfWork
{
public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
public DbSet<Order> Orders => Set<Order>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
=> modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
}
// Konfiguracja mapowania tutaj, a nie atrybutami w encji Domain
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
public void Configure(EntityTypeBuilder<Order> builder)
{
builder.HasKey(o => o.Id);
builder.Property(o => o.CustomerName).HasMaxLength(200).IsRequired();
builder.OwnsMany(o => o.Items);
}
}
public class OrderRepository : IOrderRepository
{
private readonly AppDbContext _context;
public OrderRepository(AppDbContext context) => _context = context;
public async Task AddAsync(Order order, CancellationToken ct)
=> await _context.Orders.AddAsync(order, ct);
public Task<Order?> GetByIdAsync(int id, CancellationToken ct)
=> _context.Orders.Include(o => o.Items).FirstOrDefaultAsync(o => o.Id == id, ct);
}
DbContext implementuje IUnitOfWork bez dodatkowego kodu - jego metoda SaveChangesAsync(CancellationToken) pasuje do sygnatury interfejsu. To ten sam wzorzec Repository + Unit of Work, który omawialiśmy przy EF Core.
Rejestracja zależności - każda warstwa wystawia własną metodę
// Shop.Application
public static class DependencyInjection
{
public static IServiceCollection AddApplication(this IServiceCollection services)
{
services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(DependencyInjection).Assembly));
return services;
}
}
// Shop.Infrastructure
public static class DependencyInjection
{
public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
services.AddDbContext<AppDbContext>(o => o.UseSqlServer(configuration.GetConnectionString("Default")));
services.AddScoped<IOrderRepository, OrderRepository>();
services.AddScoped<IUnitOfWork>(sp => sp.GetRequiredService<AppDbContext>());
return services;
}
}
WebApi - cienka warstwa prezentacji i Composition Root
// Program.cs - JEDYNE miejsce, które zna wszystkie warstwy
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);
builder.Services.AddControllers();
[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
private readonly ISender _sender; // MediatR
public OrdersController(ISender sender) => _sender = sender;
[HttpPost]
public async Task<IActionResult> Create(CreateOrderCommand command, CancellationToken ct)
{
var id = await _sender.Send(command, ct);
return Created($"api/orders/{id}", new { id });
}
}
Kontroler jest cienki - nie ma w nim logiki, tylko przekłada żądanie HTTP na komendę i wynik na odpowiedź HTTP. Dzięki temu można go zastąpić (gRPC, kolejka, aplikacja konsolowa, WPF) bez ruszania Application i Domain.
Przepływ pojedynczego żądania
HTTP POST /api/orders
│
▼
OrdersController (WebApi) ← tłumaczy HTTP na komendę
│ _sender.Send(command)
▼
CreateOrderHandler (Application) ← orkiestruje use case
│ new Order(...), order.AddItem(...) ← reguły w encji (Domain)
│ _orders.AddAsync(order) ← wywołanie przez INTERFEJS
▼
OrderRepository (Infrastructure) ← EF Core, SQL
│
▼
Baza danych
Granice warstw przekraczają proste dane (DTO, komendy, proste typy), a nie encje EF czy obiekty frameworka. Encje domenowe nie wychodzą do klienta HTTP - kontroler zwraca DTO (mapowane ręcznie albo przez AutoMapper), żeby zmiana modelu domenowego nie łamała kontraktu API.
Agregaty - granice spójności w warstwie Domain
Encja Order z przykładu wyżej jest w rzeczywistości korzeniem agregatu (Aggregate Root) - pojęciem z Domain-Driven Design, które świetnie pasuje do Clean Architecture, bo opisuje, jak zorganizować wnętrze warstwy Domain.
Agregat to grupa powiązanych obiektów domenowych traktowana jako jedna całość przy zmianach danych i pilnowaniu reguł biznesowych. Jeden obiekt jest korzeniem - tylko przez niego wolno z zewnątrz cokolwiek zmieniać. Pozostałe obiekty (tu OrderItem) są częściami agregatu i nie mają życia poza nim.
┌─────────────── Agregat Order ───────────────┐
│ │
│ Order (Aggregate Root) │
│ ├── OrderItem │
│ ├── OrderItem │
│ └── OrderItem │
│ │
└─────────────────────────────────────────────┘
▲ │
│ jedyne wejście │ odwołanie przez Id,
│ z zewnątrz ▼ nie przez referencję
IOrderRepository CustomerId ──► (inny agregat: Customer)
Zasady agregatu
| Zasada | Co oznacza w praktyce |
|---|---|
| Dostęp tylko przez korzeń | Nie ma order.Items.Add(...) z zewnątrz ani osobnego OrderItemRepository. Zmiany idą przez metody korzenia (order.AddItem(...)), który sprawdza reguły |
| Granica spójności | Po każdej operacji cały agregat jest spójny (np. suma zamówienia zgadza się z pozycjami, zatwierdzonego zamówienia nie można już zmieniać) |
| Jedna transakcja = jeden agregat | Zapisujesz i blokujesz agregat jako całość. Jeśli jedna operacja musi zmienić dwa agregaty, to sygnał, że granice są źle poprowadzone albo że trzeba użyć zdarzeń domenowych |
| Odwołania do innych agregatów przez Id | Order trzyma CustomerId, a nie obiekt Customer. Agregaty zostają małe i nie ciągną za sobą pół bazy |
| Jedno repozytorium na agregat | Repozytorium dotyczy korzenia: IOrderRepository, a nie IOrderItemRepository |
| Małe agregaty | Wielki agregat (np. Customer ze wszystkimi zamówieniami w środku) oznacza wolne zapytania i konflikty współbieżności |
Przykład - korzeń agregatu pilnuje niezmienników
namespace Shop.Domain.Orders;
public class Order : Entity
{
private readonly List<OrderItem> _items = new();
public int Id { get; private set; }
public int CustomerId { get; private set; } // odwołanie do innego agregatu przez Id
public OrderStatus Status { get; private set; } = OrderStatus.Draft;
public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly(); // brak publicznej listy do modyfikacji
public decimal TotalAmount => _items.Sum(i => i.UnitPrice * i.Quantity);
private Order() { }
public Order(int customerId) => CustomerId = customerId;
public void AddItem(string productName, decimal unitPrice, int quantity)
{
// Niezmiennik: zatwierdzonego zamówienia nie wolno już zmieniać
if (Status != OrderStatus.Draft)
throw new DomainException("Nie można zmieniać zatwierdzonego zamówienia.");
if (quantity <= 0)
throw new DomainException("Ilość musi być większa od zera.");
_items.Add(new OrderItem(productName, unitPrice, quantity));
}
public void Confirm()
{
// Niezmiennik: zamówienie bez pozycji nie ma sensu
if (_items.Count == 0)
throw new DomainException("Zamówienie musi mieć co najmniej jedną pozycję.");
Status = OrderStatus.Confirmed;
Raise(new OrderConfirmedEvent(Id)); // informacja dla innych agregatów
}
}
Klasa OrderItem ma internal konstruktor (albo jest zagnieżdżona), więc nikt spoza Domain nie utworzy pozycji z pominięciem zamówienia. Reguły "zatwierdzone zamówienie jest niezmienne" i "nie ma pustego zamówienia" mają jedno miejsce - w korzeniu - zamiast być rozsiane po handlerach i kontrolerach.
Komunikacja między agregatami - zdarzenia domenowe
Gdy zatwierdzenie zamówienia ma wpłynąć na inny agregat (np. zarezerwować stan magazynowy w Product), nie zmieniasz obu w jednej transakcji. Korzeń zgłasza zdarzenie domenowe, a reakcja dzieje się osobno:
// Domain - zdarzenia nie zależą od żadnej biblioteki
public interface IDomainEvent { }
public record OrderConfirmedEvent(int OrderId) : IDomainEvent;
public abstract class Entity
{
private readonly List<IDomainEvent> _events = new();
public IReadOnlyCollection<IDomainEvent> DomainEvents => _events.AsReadOnly();
protected void Raise(IDomainEvent domainEvent) => _events.Add(domainEvent);
public void ClearDomainEvents() => _events.Clear();
}
Zdarzenia są wysyłane po udanym zapisie (typowo w SaveChangesAsync w Infrastructure, np. przez MediatR INotification), a handler w Application zmienia drugi agregat w osobnej transakcji. To jest właśnie eventual consistency - spójność między agregatami nie jest natychmiastowa. Dla komunikacji między serwisami ten sam pomysł rozwijają wzorce Saga i Outbox opisane w sekcji o architekturze rozproszonej.
Jak agregat wygląda po stronie Application i Infrastructure
// Application - handler wczytuje agregat, woła jego metody, zapisuje całość
public async Task Handle(ConfirmOrderCommand command, CancellationToken ct)
{
var order = await _orders.GetByIdAsync(command.OrderId, ct)
?? throw new NotFoundException(nameof(Order), command.OrderId);
order.Confirm(); // reguły sprawdza korzeń, nie handler
await _unitOfWork.SaveChangesAsync(ct); // jedna transakcja = jeden agregat
}
// Infrastructure - konfiguracja EF Core respektuje granice agregatu
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
public void Configure(EntityTypeBuilder<Order> builder)
{
builder.HasKey(o => o.Id);
builder.OwnsMany(o => o.Items); // pozycje są CZĘŚCIĄ agregatu
builder.Property<byte[]>("RowVersion").IsRowVersion(); // optymistyczna współbieżność na całym agregacie
}
}
GetByIdAsyncwczytuje cały agregat (Include(o => o.Items)), a nie fragment - dzięki temu korzeń widzi wszystkie dane potrzebne do sprawdzenia niezmienników.RowVersionzabezpiecza przed jednoczesną zmianą tego samego agregatu przez dwóch użytkowników - drugi zapis dostanieDbUpdateConcurrencyException, zamiast po cichu nadpisać cudze zmiany.
Typowe błędy przy agregatach
- Publiczna lista modyfikowalna z zewnątrz (
public List<OrderItem> Items { get; set; }) - korzeń traci kontrolę, a reguły można obejść. WystawiajIReadOnlyCollection<T>. - Agregat-gigant -
Customerzawierający wszystkie zamówienia, adresy i płatności. Każda zmiana blokuje i ładuje całość. Dziel na mniejsze agregaty powiązane przez Id. - Referencje do obiektów innych agregatów zamiast Id - wciągają do zapytań pół bazy i zacierają granice transakcji.
- Zmiana wielu agregatów w jednej transakcji - łamie zasadę jednej transakcji na agregat; zwykle lepsze są zdarzenia domenowe.
- Logika poza korzeniem - jeśli reguły siedzą w handlerach, a encje to gettery i settery, agregat jest tylko nazwą (anemic model).
- Agregaty "na zapas" w prostym CRUD-zie - bez złożonych niezmienników DDD jest przerostem formy.
Testowalność - główny zysk w praktyce
Test use case'u bez bazy danych
public class CreateOrderHandlerTests
{
[Fact]
public async Task Handle_ValidCommand_AddsOrderAndSaves()
{
var repository = new Mock<IOrderRepository>();
var unitOfWork = new Mock<IUnitOfWork>();
var handler = new CreateOrderHandler(repository.Object, unitOfWork.Object);
var command = new CreateOrderCommand(
"Jan Kowalski",
new List<OrderItemDto> { new("Laptop", 3000m, 1) });
await handler.Handle(command, CancellationToken.None);
repository.Verify(r => r.AddAsync(
It.Is<Order>(o => o.CustomerName == "Jan Kowalski"),
It.IsAny<CancellationToken>()), Times.Once);
unitOfWork.Verify(u => u.SaveChangesAsync(It.IsAny<CancellationToken>()), Times.Once);
}
}
Test jest szybki (milisekundy), nie potrzebuje SQL Server ani WebApplicationFactory. Reguły samej encji (Order.AddItem rzuca wyjątek dla ilości ≤ 0) testuje się jeszcze prościej - czysty kod C# bez żadnych mocków.
Test architektury - pilnowanie reguły zależności
Sama struktura projektów chroni przed większością naruszeń, ale nie przed wszystkimi (np. ktoś doda referencję "bo tak szybciej"). Biblioteka NetArchTest pozwala zapisać regułę jako test:
[Fact]
public void Domain_ShouldNotDependOn_OtherLayers()
{
var result = Types.InAssembly(typeof(Order).Assembly)
.ShouldNot()
.HaveDependencyOnAny("Shop.Application", "Shop.Infrastructure", "Shop.WebApi")
.GetResult();
Assert.True(result.IsSuccessful);
}
Dzięki temu naruszenie architektury wywala build w CI, a nie wychodzi dopiero na code review.
Clean Architecture a inne podejścia
| Architektura warstwowa (N-tier) | Hexagonal / Onion | Clean Architecture | Vertical Slice | |
|---|---|---|---|---|
| Kierunek zależności | UI → Logika → Dostęp do danych (logika zależy od bazy) | Do środka (domena w centrum) | Do środka (reguła zależności) | Zależy od slice'a |
| Centrum systemu | Baza danych | Model domenowy | Encje + Use Cases | Funkcjonalność (feature) |
| Podział kodu | Po warstwach technicznych | Po warstwach, porty i adaptery | Po warstwach (kręgach) | Po funkcjonalnościach |
| Warstwa use case'ów | Zwykle rozmyta w "Services" | Niewyróżniona | Jawna, osobna | Wewnątrz slice'a |
| Typowy koszt | Mało plików, sztywna baza | Średni | Więcej projektów i interfejsów | Dużo powielenia między slice'ami |
Kluczowa różnica względem klasycznej architektury trójwarstwowej: tam warstwa biznesowa zależy od warstwy dostępu do danych (BLL referencjonuje DAL), więc zmiana bazy czy ORM-a przecieka do logiki. W Clean Architecture zależność jest odwrócona - to infrastruktura zależy od Application.
Typowe błędy i krytyka
1. Przerost formy dla prostego CRUD-a. Aplikacja, która tylko zapisuje i odczytuje formularze, nie ma "reguł biznesowych" do chronienia. Cztery projekty, interfejsy 1:1 i handler na każdą operację to wtedy czysty narzut. Dla małych projektów wystarczy prostsza struktura.
2. Anemic Domain Model. Encje to same gettery i settery, a cała logika siedzi w handlerach - wtedy "Domain" jest pustą warstwą, a architektura traci sens.
3. Przeciekanie IQueryable przez repozytorium. Jeśli IOrderRepository zwraca IQueryable<Order>, warstwa Application zaczyna zależeć od zachowań konkretnego providera EF (które operacje da się przetłumaczyć na SQL). To zepsuta abstrakcja.
4. Encje EF jako encje domenowe - pragmatyczny kompromis. Czysta wersja wymaga osobnych modeli (domenowy i persystencji) z mapowaniem między nimi. W większości projektów .NET akceptuje się, że encje domenowe są jednocześnie mapowane przez EF (z konfiguracją w Infrastructure). To świadomy kompromis, nie błąd, ale warto wiedzieć, że jest.
5. Repozytorium nad EF Core - spór. DbContext już jest Unit of Work, a DbSet repozytorium. Część zespołów rezygnuje z własnych repozytoriów i definiuje w Application interfejs IApplicationDbContext z DbSet<T>, implementowany w Infrastructure. Zyskują mniej kodu, tracą "czystość" (Application zna DbSet/IQueryable). To ten sam temat, co kontrowersje wokół Repository + Unit of Work.
6. Bezmyślne tworzenie interfejsów. Interfejs ma sens tam, gdzie jest granica (baza, zewnętrzne API, poczta). Interfejs dla klasy, która ma jedną implementację i żyje wewnątrz jednej warstwy, jest zbędny.
7. Logika w kontrolerze lub w Infrastructure. Najczęstsze naruszenie: walidacja i obliczenia lądują w kontrolerze albo w repozytorium, bo "tak było szybciej".
Kiedy ma sens
| Sytuacja | Czy Clean Architecture? |
|---|---|
| Aplikacja z rozbudowanymi regułami biznesowymi (finanse, logistyka, ubezpieczenia) | ✅ Tak - tu daje największy zysk |
| System rozwijany latami przez kilka zespołów | ✅ Tak - granice warstw porządkują pracę |
| Wymagana wysoka pokrywalność testami jednostkowymi logiki | ✅ Tak |
| Planowana możliwa zmiana technologii (baza, UI) | ✅ Tak |
| Prosty CRUD, prototyp, narzędzie wewnętrzne | ❌ Zwykle przerost formy |
| Mikroserwis z jedną, wąską odpowiedzialnością | ⚠️ Często wystarczy uproszczona wersja albo Vertical Slice |
Clean Architecture a CQRS - gdzie się spotykają
W Clean Architecture warstwa Application składa się z use case'ów, a najwygodniejszy sposób ich zapisania to komendy i zapytania - dokładnie to, co opisuje wzorzec CQRS. Szczegóły wzorca (rozdzielenie modelu zapisu i odczytu, eventual consistency, Event Sourcing) są w osobnych tematach:
- Czym jest CQRS - idea, kiedy ma sens, a kiedy jest przerostem formy,
- MediatR - jak działa i jak używać -
IRequest,IRequestHandler,Sendi pipeline behaviors.
Jak to się łączy z warstwami:
| Strona | Co robi | Którędy przechodzi |
|---|---|---|
| Komenda (zapis) | Zmienia stan, zwraca najwyżej Id lub wynik operacji | Handler → agregat w Domain (reguły biznesowe) → repozytorium → zapis w jednej transakcji |
| Zapytanie (odczyt) | Nie zmienia stanu, zwraca DTO | Handler → bezpośrednio do bazy (projekcja na DTO) - bez ładowania agregatów |
Strona zapisu przechodzi przez model domenowy, bo tam żyją niezmienniki (por. sekcja o agregatach). Strona odczytu nie ma czego chronić, więc może go pominąć i czytać dane najkrótszą drogą. Interfejs dla takiego odczytu też należy do Application, a implementacja do Infrastructure:
// Application - port dla odczytów, bez agregatów i bez EF Core
public interface IOrderQueries
{
Task<OrderDetailsDto?> GetDetailsAsync(int id, CancellationToken ct);
}
public record GetOrderQuery(int Id) : IRequest<OrderDetailsDto?>;
public class GetOrderHandler : IRequestHandler<GetOrderQuery, OrderDetailsDto?>
{
private readonly IOrderQueries _queries;
public GetOrderHandler(IOrderQueries queries) => _queries = queries;
public Task<OrderDetailsDto?> Handle(GetOrderQuery query, CancellationToken ct)
=> _queries.GetDetailsAsync(query.Id, ct);
}
// Infrastructure - szybka projekcja na DTO, bez śledzenia zmian
public class OrderQueries : IOrderQueries
{
private readonly AppDbContext _context;
public OrderQueries(AppDbContext context) => _context = context;
public Task<OrderDetailsDto?> GetDetailsAsync(int id, CancellationToken ct)
=> _context.Orders
.AsNoTracking()
.Where(o => o.Id == id)
.Select(o => new OrderDetailsDto(o.Id, o.CustomerId, o.Status.ToString(), o.Items.Sum(i => i.UnitPrice * i.Quantity)))
.FirstOrDefaultAsync(ct);
}
Dzięki temu repozytorium (IOrderRepository) obsługuje wyłącznie agregaty po stronie zapisu, a odczyty idą osobną ścieżką - to częsty, pragmatyczny kompromis w Clean Architecture, który nie wymaga osobnych baz danych (to już poziom "pełnego" CQRS). Dodatkowy zysk z MediatR: pipeline behaviors pozwalają w jednym miejscu dodać walidację, logowanie czy transakcję do wszystkich use case'ów.
Powiązania z innymi tematami z tej strony
- SOLID / DIP - reguła zależności to Dependency Inversion Principle zastosowana w skali całej aplikacji,
- IoC i DI - kontener DI w Composition Root spina warstwy, dzięki niemu Application nie tworzy infrastruktury samodzielnie,
- CQRS i MediatR - use case'y naturalnie przyjmują postać komend i zapytań z handlerami: Czym jest CQRS, MediatR,
- Repository + Unit of Work - interfejsy w Application, implementacje w Infrastructure,
- Agregaty i DDD - organizacja wnętrza warstwy Domain: korzeń agregatu pilnuje niezmienników, repozytorium jest jedno na agregat,
- Saga i Outbox - rozwinięcie komunikacji między agregatami (zdarzenia) na poziom wielu serwisów,
- AutoMapper - mapowanie encji na DTO na granicy warstw,
- Testy (xUnit, Moq) - Application testuje się z mockami portów, bez bazy.
Jak odpowiedzieć na rozmowie
Pytanie padające na rozmowie to zwykle: "Czym jest Clean Architecture i czym różni się od zwykłej architektury warstwowej?"
"Clean Architecture porządkuje kod w koncentryczne kręgi - encje domenowe w środku, potem use case'y, adaptery i na końcu szczegóły techniczne jak baza czy framework webowy. Najważniejsza jest reguła zależności: zależności w kodzie wskazują tylko do środka, więc logika biznesowa nie zna EF Core, ASP.NET ani bazy. Osiąga się to przez odwrócenie zależności - Application definiuje interfejsy, na przykład repozytorium, a Infrastructure je implementuje, całość spina kontener DI w Composition Root. W klasycznej architekturze trójwarstwowej warstwa biznesowa zależy od warstwy danych, tu jest odwrotnie. Zyskuję testowalność i możliwość wymiany szczegółów technicznych, płacę większą liczbą projektów i interfejsów, więc w prostym CRUD-ie bym tego nie stosował."
Dobra odpowiedź pokazuje trzy rzeczy: że rozumiesz kierunek zależności (nie tylko nazwy warstw), że wiesz, jak to osiągnąć w .NET (DIP, DI, osobne projekty), i że znasz koszt tego podejścia i potrafisz ocenić, kiedy się nie opłaca.
Podsumowanie
Clean Architecture ustawia logikę biznesową w centrum aplikacji i podporządkowuje jej wszystkie szczegóły techniczne za pomocą jednej reguły: zależności w kodzie wskazują wyłącznie do środka. W .NET realizuje się to czterema projektami (Domain, Application, Infrastructure, WebApi), interfejsami zdefiniowanymi w warstwie wewnętrznej i implementowanymi na zewnątrz (Dependency Inversion) oraz kontenerem DI spinającym całość w Composition Root. Wnętrze warstwy Domain porządkują agregaty - grupy obiektów z jednym korzeniem, który pilnuje niezmienników, zapisywane w jednej transakcji, powiązane z innymi agregatami przez Id i zdarzenia domenowe. Zyskuje się testowalność use case'ów bez bazy, wymienialność frameworków i ochronę reguł biznesowych, a płaci się większą ilością kodu i projektów - dlatego opłaca się przy złożonej domenie i długowiecznych systemach, a w prostym CRUD-ie jest przerostem formy.