Bạn không cần MediatR để tách command khỏi query. Bạn cần một mediator khi số handler vượt quá số người có thể nhớ toàn bộ luồng, và khi cross-cutting concern như validation, logging, transaction phải áp dụng giống nhau cho hàng chục use case. Nếu dự án chỉ có tám endpoint CRUD, thư viện mediator là thêm một lớp indirection để đổi lấy một thứ bạn chưa cần.
Cập nhật 2026
- MediatR 14.3.0 vẫn là bản mới nhất, nhưng từ v13 thư viện chuyển sang giấy phép thương mại (RPL 1.5 kèm license thương mại của Lucky Penny Software). Sản phẩm đóng nguồn dùng thương mại phải trả tiền.
- Đăng ký hiện tại là
AddMediatR(cfg => cfg.RegisterServicesFromAssemblyContaining<T>()); dùngISender/IPublisherthay choIMediatorkhi bạn chỉ cần gửi hoặc publish. - .NET 10 LTS (10.0.14) là bản production; .NET 8 và .NET 9 hết hỗ trợ ngày 2026-11-10. Toàn bộ code dưới đây chạy trên ASP.NET Core 10.
Mục lục
Vấn đề: endpoint biết quá nhiều
Một endpoint tạo đơn hàng điển hình thường bắt đầu như thế này, và lớn dần theo mỗi yêu cầu mới:
// File: src/Shop.Api/Endpoints/OrdersEndpoints.cs
app.MapPost("/orders", async (CreateOrderRequest request, OrderService orders,
EmailService email, InventoryService inventory) =>
{
var order = await orders.CreateAsync(request);
await email.SendConfirmationAsync(order.Id);
await inventory.ReserveAsync(order.Lines);
return TypedResults.Created($"/orders/{order.Id}", order.Id);
});
Ba vấn đề cùng lúc. Endpoint phụ thuộc ba service cụ thể, nên unit test phải dựng cả ba. Thứ tự gọi nằm trong endpoint, nên luồng nghiệp vụ bị chia giữa HTTP layer và service layer. Và khi thêm bước thứ tư — ghi audit, đẩy sự kiện sang analytics — bạn sửa endpoint, nghĩa là sửa code của tầng giao diện vì lý do nghiệp vụ.
Mediator: đổi lời gọi method thành một message
Mediator pattern thay lời gọi trực tiếp bằng một object mô tả việc cần làm. Người gửi chỉ cần biết “tôi muốn tạo đơn hàng”, không cần biết ai xử lý. MediatR hiện thực hóa điều đó bằng DI: nó quét assembly, tìm handler cho từng request type, và resolve handler khi bạn gửi.
Cái giá phải trả là một bước nhảy. Trong stack trace, bạn thấy Mediator.Send ở giữa; trong code, bạn phải grep từ kiểu request để tìm handler. Với team nhỏ và ít use case, cái giá này lớn hơn lợi ích. Với team mười người và hàng trăm use case, nó là thứ giữ cho endpoint luôn dài ba dòng.
IRequest, IRequestHandler và đăng ký
// File: src/Shop.Application/Orders/CreateOrder.cs
using MediatR;
public sealed record CreateOrder(Guid CustomerId, IReadOnlyList<OrderLineInput> Lines)
: IRequest<Guid>;
public sealed class CreateOrderHandler(IOrderRepository orders, IUnitOfWork uow, IPublisher publisher)
: IRequestHandler<CreateOrder, Guid>
{
public async Task<Guid> Handle(CreateOrder request, CancellationToken ct)
{
var lines = request.Lines.Select(l => new OrderLine(l.Sku, l.UnitPrice, l.Quantity));
var order = Order.Create(request.CustomerId, lines);
await orders.AddAsync(order, ct);
await uow.CommitAsync(ct);
// Publish sau commit: handler không cần biết email hay inventory tồn tại
await publisher.Publish(new OrderPlaced(order.Id, order.CustomerId), ct);
return order.Id;
}
}
Đăng ký một lần ở composition root. Đây là API của MediatR 14, không phải AddMediatR(typeof(...).Assembly) của các bản cũ:
// File: src/Shop.Api/Program.cs
builder.Services.AddMediatR(cfg =>
{
cfg.RegisterServicesFromAssemblyContaining<CreateOrder>();
cfg.AddOpenBehavior(typeof(LoggingBehavior<,>));
cfg.AddOpenBehavior(typeof(ValidationBehavior<,>));
cfg.AddOpenBehavior(typeof(TransactionBehavior<,>));
});
Endpoint không còn biết service nào; nó chỉ biết kiểu message và ISender:
app.MapPost("/orders", async (CreateOrder command, ISender sender, CancellationToken ct) =>
{
var id = await sender.Send(command, ct);
return TypedResults.Created($"/orders/{id}", id);
});
Một request chỉ có đúng một handler. Nếu bạn cần hai thứ cùng phản ứng với một việc, đó là notification, không phải request — và đó là ranh giới quan trọng nhất trong bài này.
CQRS: command và query không cùng hình dạng
CQRS không phải thư viện, nó là quyết định tách đường ghi khỏi đường đọc. Command trả về id hoặc không trả gì; query trả về DTO đã đóng gói cho màn hình. Hai bên có thể dùng model khác nhau, tối ưu khác nhau, thậm chí database khác nhau.
| Tiêu chí | Command | Query |
|---|---|---|
| Mục đích | Thay đổi trạng thái | Đọc dữ liệu |
| Kết quả | Id, số dòng, hoặc không | DTO phẳng cho một màn hình |
| Truy vấn | Load aggregate, giữ invariant | AsNoTracking, projection, có thể Dapper |
| Transaction | Có | Không |
// File: src/Shop.Application/Orders/GetOrder.cs
public sealed record GetOrder(Guid Id) : IRequest<OrderSummary?>;
public sealed record OrderSummary(Guid Id, Guid CustomerId, OrderStatus Status);
public sealed class GetOrderHandler(ShopDbContext db)
: IRequestHandler<GetOrder, OrderSummary?>
{
public Task<OrderSummary?> Handle(GetOrder request, CancellationToken ct)
=> db.Orders
.AsNoTracking()
.Where(o => o.Id == request.Id)
.Select(o => new OrderSummary(o.Id, o.CustomerId, o.Status))
.FirstOrDefaultAsync(ct);
}
AsNoTracking và projection là hai thứ biến query khỏi việc load cả aggregate rồi map. Nếu màn hình cần join năm bảng, viết query riêng hoặc dùng Dapper 2.1.89 — đừng nhồi vào repository của luồng ghi.
Tách database đọc và ghi chỉ đáng làm khi hai bên có nhu cầu thật sự khác nhau: read model cần tìm kiếm full-text, hoặc tải đọc gấp nhiều lần tải ghi. Với phần lớn ứng dụng, dùng cùng một database nhưng query có AsNoTracking và projection là đủ; tách vật lý sớm chỉ thêm bài toán đồng bộ và độ trễ mà không ai trả tiền cho.
Notification: side effect tách khỏi luồng chính
// File: src/Shop.Application/Orders/OrderPlaced.cs
public sealed record OrderPlaced(Guid OrderId, Guid CustomerId) : INotification;
public sealed class SendConfirmationEmail(IEmailSender email, ILogger<SendConfirmationEmail> logger)
: INotificationHandler<OrderPlaced>
{
public async Task Handle(OrderPlaced notification, CancellationToken ct)
{
await email.SendAsync(notification.CustomerId, notification.OrderId, ct);
logger.LogInformation("Đã gửi xác nhận cho đơn {OrderId}", notification.OrderId);
}
}
Notification có thể có nhiều handler và chúng chạy tuần tự trong cùng scope DI. Điều này tiện cho side effect nội bộ, nhưng có ba cạm bẫy. Handler ném exception sẽ làm hỏng cả request dù dữ liệu đã commit. Thứ tự handler không được bảo đảm theo ý bạn. Và publish trong process không bền vững: process chết là event mất. Với email, inventory hay thanh toán, hãy ghi outbox trong transaction rồi publish từ worker; MediatR chỉ là lớp dispatch, không phải message broker.
Pipeline behaviors: validation, logging, transaction
Behavior là middleware của mediator. Nó bọc quanh mọi handler cùng kiểu, nên cross-cutting concern không phải lặp trong từng handler. Ví dụ validation với FluentValidation 12.2:
// File: src/Shop.Application/Behaviors/ValidationBehavior.cs
public sealed class ValidationBehavior<TRequest, TResponse>(IEnumerable<IValidator<TRequest>> validators)
: IPipelineBehavior<TRequest, TResponse> where TRequest : notnull
{
public async Task<TResponse> Handle(TRequest request,
RequestHandlerDelegate<TResponse> next, CancellationToken ct)
{
if (validators.Any())
{
var context = new ValidationContext<TRequest>(request);
var results = await Task.WhenAll(validators.Select(v => v.ValidateAsync(context, ct)));
var failures = results.SelectMany(r => r.Errors).Where(f => f is not null).ToList();
if (failures.Count != 0) throw new ValidationException(failures);
}
return await next(ct);
}
}
Lưu ý: FluentValidation 12 bỏ auto-validation của ASP.NET Core (đã bị remove từ v11), nên behavior này chính là chỗ bạn gọi validator. Nếu dùng Minimal API, bạn có thể chọn AddValidation() có sẵn của ASP.NET Core 10 với DataAnnotations thay vì FluentValidation — đừng dựng cả hai hệ thống validation.
// File: src/Shop.Application/Behaviors/TransactionBehavior.cs
public sealed class TransactionBehavior<TRequest, TResponse>(IUnitOfWork uow)
: IPipelineBehavior<TRequest, TResponse> where TRequest : notnull
{
public async Task<TResponse> Handle(TRequest request,
RequestHandlerDelegate<TResponse> next, CancellationToken ct)
{
var response = await next(ct);
await uow.CommitAsync(ct);
return response;
}
}
Chỉ chọn một nơi commit: handler hoặc behavior, không cả hai. Logging behavior tương tự, nhưng hãy log sau khi handler chạy để có thời gian và kết quả; log trước chỉ cho bạn biết request đến, không cho biết nó có thành công.
License: điều phải biết trước khi chọn
Từ v13, MediatR không còn miễn phí cho mọi trường hợp. Với sản phẩm thương mại đóng nguồn, bạn cần license thương mại; RPL 1.5 là giấy phép có tính chất reciprocal, không phải MIT. Với dự án mã nguồn mở tương thích RPL hoặc dùng cá nhân, điều khoản khác nhau — đọc trước khi đưa vào kiến trúc, vì thay mediator sau hai năm là việc tốn kém.
| Lựa chọn | Dạng | Ghi chú |
|---|---|---|
| MediatR 14.3.0 | Mediator in-process, pipeline behavior | Thương mại từ v13 |
| Wolverine | Mediator + messaging/outbox | Kiểm tra license và độ chín trước khi chọn |
| FastEndpoints | REPR: endpoint + handler, không mediator | Ít indirection, phù hợp API nhiều endpoint |
| Handler tự viết | Interface + DI | Không dependency, kiểm soát hoàn toàn |
Điểm quan trọng: mediator chỉ là một cách gọi handler. Bạn có thể có CQRS đúng nghĩa với handler tự viết, như trong bài Clean Architecture của series. Đừng để quyết định kiến trúc bị khóa bởi một dependency thương mại.
Nếu đang cân nhắc rời MediatR, đường đi ít đau nhất là giữ nguyên hình dạng message: mỗi command/query vẫn là một record, mỗi handler vẫn là một lớp với method HandleAsync. Bạn chỉ thay ISender.Send bằng một interface tự viết và đăng ký bằng DI. Phần lớn code nằm trong handler chứ không nằm trong mediator, nên chi phí chuyển đổi thường chỉ là vài chục dòng ở composition root và endpoint.
Khi MediatR là thừa
- Dưới khoảng 20 endpoint, một team, không có cross-cutting behavior phức tạp.
- Luồng nghiệp vụ đơn giản, mỗi command chỉ gọi một service có sẵn.
- Team chưa quen grep theo kiểu message — debugging sẽ tốn thời gian hơn tiết kiệm được.
- Bạn đang dùng Minimal API với endpoint function ngắn; thêm mediator chỉ tạo hai lớp thay vì một.
Sáu cái bẫy
- Handler bùng nổ. Mỗi thao tác nhỏ thành một cặp request/handler riêng, kể cả
GetCustomerName. Gom các query cùng màn hình vào một handler trả về một DTO. - Luồng ẩn. Endpoint gọi một command, command publish notification, notification gọi command khác. Ba lớp ẩn và không ai đọc được thứ tự thực thi. Vẽ sơ đồ luồng cho mỗi use case quan trọng.
- Handler gọi handler.
Sendlồng trongSendlàm transaction và behavior chồng lên nhau, log trùng, lỗi khó lần. Tách thành service dùng chung hoặc notification. - Logic miền trong handler. Handler phình thành service 300 dòng. Quy tắc phải ở entity; handler chỉ điều phối.
- Fire-and-forget.
_ = publisher.Publish(...)nuốt exception và làm mất event khi shutdown. Await, hoặc đẩy qua outbox. - Publish trước commit. Handler đọc dữ liệu chưa ghi, hoặc email gửi cho đơn hàng sau đó rollback. Publish sau commit, và với side effect quan trọng thì dùng outbox.
Checklist và hướng 2027
- Đo trước khi thêm mediator: số endpoint, số cross-cutting concern, số người trong team.
- Chốt license trước khi viết 40 handler; đọc điều khoản RPL 1.5 nếu sản phẩm là thương mại.
- Command trả id, query trả DTO; không dùng chung model cho cả hai.
- Publish sau commit; side effect quan trọng đi qua outbox.
- Một commit point duy nhất, và log sau khi handler chạy xong.
Năm 2027, .NET 12 LTS dự kiến ra mắt sau .NET 11 (GA tháng 11/2026, STS). Về mediator, xu hướng rõ nhất không phải thư viện mới mà là việc team cân nhắc license trước khi đưa dependency vào kiến trúc, và dùng message broker hoặc outbox cho side effect thay vì coi notification in-process là đủ tin cậy.
Đọc tiếp trong series
- Kiến trúc sạch (Clean Architecture) trong ASP.NET Core — vị trí của Application layer và handler.
- Thiết kế hướng miền (DDD) trong ASP.NET Core — domain event và aggregate.
- FluentValidation để kiểm soát đầu vào — chi tiết validator trong pipeline.
- ASP.NET Core Roadmap 2026 — toàn bộ lộ trình.



