C# / .NET Kompendium PLEN
.NET / C# / CQRS, MediatR

CQRS - Command Query Responsibility Segregation

Fundamentalna idea

CQRS to wzorzec architektoniczny, który mówi: operacje zmieniające stan (Command) powinny być rozdzielone od operacji tylko odczytujących dane (Query) - to dwa różne modele, nawet jeśli operują na tych samych danych.

// Command - ZMIENIA stan, zwykle nie zwraca danych (albo tylko Id/status)
public record CreateOrderCommand(string CustomerName, List<OrderItemDto> Items);

// Query - TYLKO CZYTA, nigdy nie zmienia stanu
public record GetOrderQuery(int OrderId);

Dlaczego to rozdzielenie ma sens

Bez CQRS - jeden serwis robi wszystko, model danych do odczytu i zapisu jest identyczny:

public class OrderService
{
    public async Task<Order> GetOrderAsync(int id) { /* ... */ }
    public async Task CreateOrderAsync(Order order) { /* ... */ }
    public async Task UpdateOrderStatusAsync(int id, string status) { /* ... */ }
}

To działa dobrze dla prostych aplikacji CRUD, ale zaczyna szwankować, gdy: - Odczyt i zapis mają zupełnie różne wymagania wydajnościowe - odczyt (Query) często potrzebuje zoptymalizowanych, zdenormalizowanych widoków (np. raport sprzedaży łączący dane z 5 tabel), a zapis (Command) potrzebuje pełnej walidacji i logiki biznesowej - Model danych do wyświetlenia różni się od modelu domenowego - lista zamówień w UI potrzebuje innego "kształtu" danych niż encja Order używana przy przetwarzaniu zamówienia - Chcesz oddzielnie skalować odczyty i zapisy (np. więcej instancji dla odczytu, bo tego jest więcej)

Command - reprezentuje intencję zmiany

public record PlaceOrderCommand(string CustomerName, List<OrderItemDto> Items);

public class PlaceOrderHandler
{
    private readonly AppDbContext _context;

    public async Task<int> Handle(PlaceOrderCommand command)
    {
        var order = new Order { CustomerName = command.CustomerName };
        // logika biznesowa, walidacja, itd.
        _context.Orders.Add(order);
        await _context.SaveChangesAsync();
        return order.Id; // zwraca TYLKO to, co niezbędne (np. Id nowego zamówienia)
    }
}

Zasada: Command nie powinien zwracać dużych zestawów danych - to nie jego rola. Zwraca maksymalnie Id, status sukcesu, albo nic.

Query - reprezentuje żądanie danych, BEZ efektów ubocznych

public record GetOrderSummaryQuery(int OrderId);

public class GetOrderSummaryHandler
{
    private readonly AppDbContext _context;

    public async Task<OrderSummaryDto> Handle(GetOrderSummaryQuery query)
    {
        // Może to być zoptymalizowane zapytanie, inne niż to używane przy Command
        return await _context.Orders
            .Where(o => o.Id == query.OrderId)
            .Select(o => new OrderSummaryDto(o.Id, o.CustomerName, o.Items.Count, o.TotalAmount))
            .FirstOrDefaultAsync();
    }
}

Zasada: Query nigdy nie zmienia stanu - to musi być całkowicie bezpieczne do wielokrotnego wywołania (idempotentne), bez żadnych efektów ubocznych.

CQRS nie wymaga osobnych baz danych - to częste błędne przekonanie

To jest ważne rozróżnienie, o które często pytają na rozmowach: CQRS to wzorzec na poziomie kodu/architektury aplikacji - rozdzielenie Command i Query jako osobnych klas/modeli. Nie musisz mieć osobnej bazy do odczytu i osobnej do zapisu (to jest dodatkowa, opcjonalna technika, nazywana CQRS z osobnymi magazynami danych, często łączona z Event Sourcing) - w większości aplikacji biznesowych CQRS działa na tej samej bazie danych, tylko z rozdzielonymi modelami/klasami w kodzie.

Prosty CQRS (najczęstszy w praktyce):
Command → ta sama baza danych ← Query
(rozdzielone tylko w KODZIE - różne klasy, różne modele)

Zaawansowany CQRS (rzadszy, dla dużej skali):
Command → baza zapisu (write model)
              ↓ synchronizacja (np. przez event/message queue)
Query → osobna baza odczytu (read model, zdenormalizowana, zoptymalizowana pod konkretne zapytania)

Relacja do wcześniejszej rozmowy o Repository/UoW

To nawiązuje do dyskusji o Repository - w architekturze CQRS Command Handler często pisze bezpośrednio przez DbContext (potrzebuje pełnego modelu domenowego z logiką biznesową), a Query Handler może pisać bardzo uproszczone, zoptymalizowane zapytania LINQ z projekcją bezpośrednio na DTO (Select(o => new OrderSummaryDto(...))), bez przechodzenia przez pełne encje domenowe - to jest miejsce, gdzie "generyczne repozytorium" (GetAllAsync() zwracające pełne encje) staje się szczególnie niewygodne, bo tłamsi możliwość takiej optymalizacji.

Kto woła handlery? Brakujące ogniwo

Handler sam się nie uruchamia - to zwykła klasa z metodą Handle(). Wywołuje go punkt wejścia aplikacji (warstwa prezentacji): kontroler MVC / endpoint Minimal API, konsument kolejki (RabbitMQ, Kafka), zadanie w tle (BackgroundService, Hangfire) albo ViewModel w WPF/Blazor. Handler nie wie i nie powinien wiedzieć, kto go woła - dzięki temu ten sam use case można uruchomić z API, z kolejki i z testu.

Klient (HTTP) → Kontroler / Endpoint → Handler → DbContext → baza
                  (mapuje request      (cała logika  
                   na Command/Query)    use case'u)
                        ↑                    │
                        └──── wynik (Id / DTO) ┘

Są dwa sposoby, żeby punkt wejścia dostał właściwy handler. Zacznijmy od tego bez żadnej biblioteki, bo pokazuje całą mechanikę.

Wariant 1: kontroler woła handler bezpośrednio (bez MediatR)

Wspólne interfejsy dla handlerów:

public interface ICommandHandler<in TCommand, TResult>
{
    Task<TResult> Handle(TCommand command, CancellationToken ct);
}

public interface IQueryHandler<in TQuery, TResult>
{
    Task<TResult> Handle(TQuery query, CancellationToken ct);
}

// Handlery implementują interfejsy
public class PlaceOrderHandler : ICommandHandler<PlaceOrderCommand, int>
{
    private readonly AppDbContext _context;
    public PlaceOrderHandler(AppDbContext context) => _context = context;

    public async Task<int> Handle(PlaceOrderCommand command, CancellationToken ct)
    {
        var order = new Order { CustomerName = command.CustomerName };
        _context.Orders.Add(order);
        await _context.SaveChangesAsync(ct);
        return order.Id;
    }
}

public class GetOrderSummaryHandler : IQueryHandler<GetOrderSummaryQuery, OrderSummaryDto?>
{
    private readonly AppDbContext _context;
    public GetOrderSummaryHandler(AppDbContext context) => _context = context;

    public Task<OrderSummaryDto?> Handle(GetOrderSummaryQuery query, CancellationToken ct) =>
        _context.Orders
            .Where(o => o.Id == query.OrderId)
            .Select(o => new OrderSummaryDto(o.Id, o.CustomerName, o.Items.Count, o.TotalAmount))
            .FirstOrDefaultAsync(ct);
}

Rejestracja w DI (Program.cs) - każdy handler jako Scoped, bo korzysta z DbContext:

builder.Services.AddScoped<ICommandHandler<PlaceOrderCommand, int>, PlaceOrderHandler>();
builder.Services.AddScoped<IQueryHandler<GetOrderSummaryQuery, OrderSummaryDto?>, GetOrderSummaryHandler>();

I właśnie kontroler jest tym, kto woła handlery - dostaje je przez konstruktor (DI) i tłumaczy żądanie HTTP na Command/Query:

[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
    private readonly ICommandHandler<PlaceOrderCommand, int> _placeOrder;
    private readonly IQueryHandler<GetOrderSummaryQuery, OrderSummaryDto?> _getOrder;

    public OrdersController(
        ICommandHandler<PlaceOrderCommand, int> placeOrder,
        IQueryHandler<GetOrderSummaryQuery, OrderSummaryDto?> getOrder)
    {
        _placeOrder = placeOrder;
        _getOrder = getOrder;
    }

    [HttpPost]
    public async Task<IActionResult> Create(PlaceOrderRequest request, CancellationToken ct)
    {
        // 1. kontroler tylko mapuje request HTTP na Command
        var command = new PlaceOrderCommand(request.CustomerName, request.Items);

        // 2. woła handler i dostaje wynik (Id)
        var orderId = await _placeOrder.Handle(command, ct);

        // 3. zamienia wynik na odpowiedź HTTP
        return CreatedAtAction(nameof(Get), new { id = orderId }, orderId);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> Get(int id, CancellationToken ct)
    {
        var dto = await _getOrder.Handle(new GetOrderSummaryQuery(id), ct);
        return dto is null ? NotFound() : Ok(dto);
    }
}

W Minimal API to samo, tylko handler trafia jako parametr endpointu (DI wstrzykuje go automatycznie):

app.MapPost("/api/orders", async (
    PlaceOrderRequest request,
    ICommandHandler<PlaceOrderCommand, int> handler,
    CancellationToken ct) =>
{
    var id = await handler.Handle(new PlaceOrderCommand(request.CustomerName, request.Items), ct);
    return Results.Created($"/api/orders/{id}", id);
});

Plus tego wariantu: zero "magii" - w IDE przechodzisz z kontrolera wprost do handlera (F12). Minus: kontroler z wieloma akcjami dostaje długą listę handlerów w konstruktorze ("constructor bloat"), a każdy nowy handler trzeba ręcznie zarejestrować w DI (można to zautomatyzować skanowaniem assembly, np. biblioteką Scrutor).

Wariant 2: kontroler woła mediatora, a mediator woła handler

Żeby uniknąć długiej listy zależności, wprowadza się pośrednika (Mediator / dispatcher). Kontroler zna tylko jego i wysyła mu Command/Query, a pośrednik sam znajduje w DI właściwy handler po typie komunikatu. Gotową implementacją jest MediatR - pełny opis i przykład kontrolera z IMediator jest w temacie MediatR - jak działa i jak używać:

// Kontroler: jedna zależność zamiast N handlerów
var orderId = await _mediator.Send(new PlaceOrderCommand(request.CustomerName, request.Items));
//                 ↑ MediatR znajduje PlaceOrderHandler w DI i wywołuje jego Handle()

Dodatkowa korzyść: skoro wszystko przechodzi przez jeden punkt, można w nim podpiąć walidację, logowanie i transakcje (Pipeline Behaviors).

Pełny przepływ - co dokładnie się dzieje

  1. Klient wysyła POST /api/orders z JSON-em.
  2. ASP.NET Core wykonuje model binding i tworzy kontroler (DI wstrzykuje handler albo IMediator).
  3. Kontroler buduje PlaceOrderCommand i woła handler (bezpośrednio albo przez mediatora).
  4. Handler wykonuje use case: reguły biznesowe, zapis przez DbContext, SaveChangesAsync.
  5. Handler zwraca Id; kontroler zamienia je na 201 Created.
  6. Przy GET ten sam schemat, ale z Query Handlerem, który tylko czyta i zwraca DTO.

Kto jeszcze może wołać handlery

  • Konsument kolejki - komunikat z RabbitMQ/Kafka jest zamieniany na Command i trafia do tego samego handlera, którego używa API.
  • Zadanie w tle (BackgroundService, Hangfire) - np. nocny przeliczeniowy Command. Pamiętaj o utworzeniu scope DI (IServiceScopeFactory), bo handler jest Scoped.
  • Test jednostkowy / integracyjny - tworzy handler i woła Handle() bez HTTP.
  • Inny handler - technicznie możliwe, ale zwykle to zapach; zamiast tego użyj zdarzeń domenowych albo wydziel wspólną logikę do serwisu domenowego.

Zasady, które warto zapamiętać

  • Kontroler jest cienki - mapuje request na Command/Query, woła handler, mapuje wynik na odpowiedź. Żadnej logiki biznesowej.
  • Query Handler nigdy nie woła Command Handlera i nie zmienia stanu.
  • Jeden handler = jeden use case; handler nie zna HTTP (HttpContext, IActionResult) - dzięki temu działa z każdego punktu wejścia.
  • Rozdział Command/Query dotyczy kodu, nie transportu: oba mogą iść tym samym endpointem HTTP i tą samą bazą.

Zalety CQRS

  • Jasność intencji - patrząc na PlaceOrderCommand, wiesz dokładnie, co ta operacja robi, bez czytania implementacji
  • Możliwość niezależnej optymalizacji odczytu i zapisu
  • Łatwiejsze testowanie - Command/Query to proste, niemutowalne obiekty danych (świetny przykład dla record, o którym mówiliśmy!) z jednym Handlerem do przetestowania
  • Skalowalność - w bardziej złożonych systemach, odczyty i zapisy mogą być skalowane niezależnie

Wady/koszty CQRS

  • Więcej kodu dla prostych operacji CRUD - dla trywialnej aplikacji "dodaj/edytuj/usuń" bez złożonej logiki biznesowej, CQRS może być przerostem formy nad treścią
  • Potencjalna duplikacja modeli (Command DTO, Query DTO, encja domenowa mogą wyglądać podobnie, ale są odrębnymi typami)

Kiedy stosować CQRS - praktyczna reguła

CQRS ma sens, gdy logika zapisu (walidacja, reguły biznesowe, efekty domenowe) jest istotnie różna od logiki odczytu (raportowanie, wyświetlanie, wyszukiwanie) - typowo w większych, złożonych systemach biznesowych. Dla prostych CRUD-ów (mały wewnętrzny panel administracyjny) klasyczny serwis z jedną klasą często wystarczy, bez narzutu dodatkowej struktury.

Postaw mi kawę