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
- Klient wysyła
POST /api/ordersz JSON-em. - ASP.NET Core wykonuje model binding i tworzy kontroler (DI wstrzykuje handler albo
IMediator). - Kontroler buduje
PlaceOrderCommandi woła handler (bezpośrednio albo przez mediatora). - Handler wykonuje use case: reguły biznesowe, zapis przez
DbContext,SaveChangesAsync. - Handler zwraca
Id; kontroler zamienia je na201 Created. - Przy
GETten 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 jestScoped. - 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.