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

CQRS z MediatR - mechanika implementacji

MediatR - biblioteka implementująca wzorzec Mediator

MediatR to popularna biblioteka .NET realizująca wzorzec Mediator - pośrednika, przez którego przechodzą wszystkie Command/Query, zamiast wywoływać Handler-y bezpośrednio.

// Definicja Command - implementuje IRequest<TResponse> z MediatR
public record PlaceOrderCommand(string CustomerName, List<OrderItemDto> Items) : IRequest<int>;

// Definicja Query
public record GetOrderQuery(int OrderId) : IRequest<OrderDto>;

Handler - implementuje logikę dla konkretnego Command/Query

public class PlaceOrderHandler : IRequestHandler<PlaceOrderCommand, int>
{
    private readonly AppDbContext _context;

    public PlaceOrderHandler(AppDbContext context) => _context = context;

    public async Task<int> Handle(PlaceOrderCommand request, CancellationToken cancellationToken)
    {
        var order = new Order { CustomerName = request.CustomerName };
        foreach (var item in request.Items)
        {
            order.Items.Add(new OrderItem { ProductId = item.ProductId, Quantity = item.Quantity });
        }

        _context.Orders.Add(order);
        await _context.SaveChangesAsync(cancellationToken);

        return order.Id;
    }
}

Kluczowa zasada: jeden Handler na jeden Command/Query - to jest 1:1 mapowanie, w przeciwieństwie do tradycyjnego serwisu, który mógł mieć wiele metod. To wspiera Single Responsibility Principle (z SOLID) na poziomie operacji, nie tylko klasy.

Kontroler - wysyła przez IMediator, nie woła serwisu bezpośrednio

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator; // JEDYNA zależność - nie potrzeba wstrzykiwać 10 serwisów!

    public OrdersController(IMediator mediator) => _mediator = mediator;

    [HttpPost]
    public async Task<ActionResult<int>> CreateOrder(PlaceOrderCommand command)
    {
        var orderId = await _mediator.Send(command); // MediatR znajduje odpowiedni Handler i go wywołuje
        return CreatedAtAction(nameof(GetOrder), new { id = orderId }, orderId);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<OrderDto>> GetOrder(int id)
    {
        var order = await _mediator.Send(new GetOrderQuery(id));
        return order == null ? NotFound() : Ok(order);
    }
}

To jest znacząca zmiana architektoniczna - Controller nie ma wstrzykiwanego IOrderService z dziesiątkami metod. Ma tylko IMediator, a MediatR automatycznie znajduje właściwy Handler na podstawie typu przekazanego Command/Query.

Jak MediatR "wie", który Handler wywołać - mechanika

// Rejestracja w DI (Program.cs)
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

MediatR przy starcie skanuje assembly, znajduje wszystkie klasy implementujące IRequestHandler<TRequest, TResponse>, i automatycznie rejestruje je w kontenerze DI. Gdy wywołujesz _mediator.Send(command):

// W przybliżeniu, co dzieje się "pod spodem" w MediatR:
public async Task<TResponse> Send<TResponse>(IRequest<TResponse> request)
{
    var requestType = request.GetType(); // np. typeof(PlaceOrderCommand)
    var handlerType = typeof(IRequestHandler<,>).MakeGenericType(requestType, typeof(TResponse));

    var handler = _serviceProvider.GetRequiredService(handlerType); // rozwiązanie z DI kontenera

    return await ((dynamic)handler).Handle((dynamic)request, cancellationToken);
}

To jest w zasadzie generyczny Service Locator, ale zamknięty tylko na Command/Query, w kontrolowany sposób (w przeciwieństwie do anty-patternu Service Locator, o którym mówiliśmy przy sposobach DI, tutaj mapowanie typ→handler jest jawne i sprawdzane w compile-time przez system typów IRequestHandler<TRequest, TResponse>).

Pipeline Behaviors - middleware dla Command/Query (bardzo praktyczna funkcja)

To jest jedna z najbardziej wartościowych cech MediatR - możliwość dodania przekrojowej logiki (cross-cutting concerns), która wykonuje się dla WSZYSTKICH (albo wybranych) Command/Query, bez duplikowania kodu w każdym Handlerze:

public class ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IValidator<TRequest> _validator;

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next, // "kontynuacja" - następny krok w łańcuchu
        CancellationToken cancellationToken)
    {
        var validationResult = await _validator.ValidateAsync(request);
        if (!validationResult.IsValid)
            throw new ValidationException(validationResult.Errors);

        return await next(); // przekazanie dalej, do właściwego Handlera (albo kolejnego behaviora)
    }
}
public class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
    {
        _logger.LogInformation($"Przetwarzanie {typeof(TRequest).Name}");
        var response = await next();
        _logger.LogInformation($"Zakończono {typeof(TRequest).Name}");
        return response;
    }
}
// Rejestracja - kolejność ma znaczenie, tworzy "łańcuch"
builder.Services.AddTransient(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
builder.Services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));

To jest dokładnie ten sam mechanizm IoC ("Twój kod jest wywoływany przez framework, w łańcuchu z next()"), o którym mówiliśmy przy ASP.NET Core middleware - Pipeline Behaviors w MediatR to middleware, ale na poziomie Command/Query, nie requestów HTTP.

Praktyczne zastosowania Pipeline Behaviors: - Walidacja (jak wyżej, często z biblioteką FluentValidation) - Logowanie każdej operacji - Transakcje (owinięcie Handle() w BeginTransactionAsync/CommitAsync) - Cache'owanie wyników Query - Pomiar czasu wykonania (performance monitoring)

FluentValidation + MediatR - typowa kombinacja

public class PlaceOrderCommandValidator : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderCommandValidator()
    {
        RuleFor(x => x.CustomerName).NotEmpty().MaximumLength(100);
        RuleFor(x => x.Items).NotEmpty().WithMessage("Zamówienie musi mieć przynajmniej jedną pozycję");
    }
}

Handler nie musi zawierać ręcznej walidacji - ValidationBehavior (Pipeline Behavior wyżej) automatycznie ją wykonuje przed wywołaniem Handle() każdego Command/Query, dla którego istnieje odpowiedni walidator.

Zalety takiej architektury

  • Kontroler jest bardzo tani - jedna zależność (IMediator), zamiast rosnącej listy serwisów wstrzykiwanych przez konstruktor (wracamy do "constructor bloat", o którym mówiliśmy przy DI)
  • Przekrojowa logika w jednym miejscu (Pipeline Behaviors) - nie musisz pamiętać o dodaniu logowania/walidacji w każdym nowym Handlerze
  • Testowanie Handlera w izolacji - Handler to prosta klasa z jedną metodą Handle(), łatwa do przetestowania bez mockowania kontrolera czy HTTP

Wady/koszty

  • "Magia" utrudniająca śledzenie przepływu - żeby zrozumieć, co się dzieje przy _mediator.Send(command), musisz wiedzieć o istnieniu MediatR i mechanizmie rejestracji Handlerów - to nie jest tak jawne jak bezpośrednie wywołanie metody serwisu (_orderService.CreateOrder(...))
  • Więcej plików/klas dla prostych operacji (Command + Handler + Validator dla czegoś, co mogłoby być jedną metodą serwisu)

Podsumowanie

MediatR implementuje CQRS przez wzorzec Mediator - Command/Query to proste, niemutowalne obiekty (dobre zastosowanie record, o którym rozmawialiśmy), Handler implementuje logikę dla jednego konkretnego typu żądania, a Pipeline Behaviors dodają przekrojową logikę (walidację, logowanie, transakcje) bez duplikacji kodu w każdym Handlerze. Kontroler staje się bardzo "tani" - potrzebuje tylko IMediator, resztę załatwia framework przez mechanizm rejestracji i rozwiązywania Handlerów z kontenera DI.

Postaw mi kawę