C# / .NET Kompendium PLEN
.NET / C# / SOLID, Clean Code, DI

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
    }
}
  • GetByIdAsync wczytuje cały agregat (Include(o => o.Items)), a nie fragment - dzięki temu korzeń widzi wszystkie dane potrzebne do sprawdzenia niezmienników.
  • RowVersion zabezpiecza przed jednoczesną zmianą tego samego agregatu przez dwóch użytkowników - drugi zapis dostanie DbUpdateConcurrencyException, 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ść. Wystawiaj IReadOnlyCollection<T>.
  • Agregat-gigant - Customer zawierają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:

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.

Postaw mi kawę