Vấn đề với các Fat Controller
Hầu hết các backend developer khi mới bắt đầu thường xây dựng REST API theo hướng để controller ôm đồm mọi thứ. Một controller action duy nhất vừa tiếp nhận HTTP payload, chạy kiểm tra validation, truy vấn cơ sở dữ liệu qua EF Core, tính toán giá thành, lại vừa format response trả về dạng JSON. Cách làm tắt này có thể chạy tốt với các dự án prototype hay trong các buổi hackathon ngắn hạn.
Tuy nhiên, khi hệ thống mở rộng, pattern này sẽ nhanh chóng bộc lộ điểm yếu. Chỉ trong vòng sáu tháng, một OrdersController thông thường có thể phình to lên hơn 1.200 dòng. Các câu truy vấn LINQ thuần nằm rải rác khắp hàng chục endpoint. Việc thay đổi một công thức tính thuế nhỏ cũng có nguy cơ làm gián đoạn cùng lúc quy trình thanh toán của khách hàng, việc xuất hóa đơn và các báo cáo quản trị. Viết unit test trở thành một cơn ác mộng vì để kiểm tra một HTTP status code đơn giản, bạn phải mock toàn bộ database context cùng ba external HTTP client khác nhau.
Chúng ta cần những ranh giới phân tách rõ ràng. Business rule phải tồn tại độc lập với cơ sở dữ liệu, presentation framework và các transport protocol.
Các khái niệm cốt lõi: Clean Architecture, CQRS và MediatR
Clean Architecture tổ chức mã nguồn thành các tầng đồng tâm. Chiều phụ thuộc (dependency) chỉ được phép hướng vào trong. Các tầng bên trong định nghĩa contract (giao diện); các tầng bên ngoài cung cấp phần triển khai thực tế (implementation).
- Domain Layer: Chứa các entity cốt lõi, value object, business rule và domain exception. Tầng này hoàn toàn không phụ thuộc vào bất kỳ thư viện bên ngoài nào.
- Application Layer: Điều phối các use case. Tầng này định nghĩa các repository interface, DTO, MediatR command, query và pipeline xử lý nghiệp vụ.
- Infrastructure Layer: Xử lý các mối quan tâm bên ngoài (external concerns). Bao gồm DbContext của EF Core, Redis cache, SendGrid client và các background worker.
- Presentation Layer: Đóng vai trò giao tiếp với thế giới bên ngoài thông qua ASP.NET Core Controller hoặc Minimal API.
Bên trong tầng Application, chúng ta triển khai CQRS (Command Query Responsibility Segregation). CQRS tách biệt hoàn toàn thao tác đọc (read) và thao tác ghi (write):
- Command: Thay đổi trạng thái hệ thống (chẳng hạn như
CreateProductCommand). Nhóm này tập trung vào validation và đảm bảo các bất biến nghiệp vụ (domain invariants). - Query: Lấy dữ liệu mà không làm thay đổi trạng thái (chẳng hạn như
GetProductByIdQuery). Nhóm này bỏ qua các domain entity nặng nề và map trực tiếp sang các DTO phẳng.
Thay vì inject năm interface dịch vụ khác nhau vào constructor của từng controller, chúng ta chỉ cần inject ISender của MediatR. MediatR đóng vai trò như một in-process mediator. Controller sẽ dispatch một request object, và MediatR sẽ chuyển nó đến handler tương ứng. Trong một dự án có 12 lập trình viên cùng làm việc trên 50 endpoint, pattern này giúp giảm thiểu đáng kể xung đột mã nguồn (merge conflict) và giữ cho các method trong controller không quá 10 dòng.
Thực hành: Xây dựng Catalog API cho E-Commerce trong .NET 9
Hãy cùng xây dựng một catalog service hoàn chỉnh từ thư mục trống bằng cách sử dụng .NET 9 CLI.
Bước 1: Thiết lập Solution và các Project
Chạy các lệnh terminal sau để tạo cấu trúc dự án 4 tầng:
# Tạo thư mục solution
mkdir CleanCatalog && cd CleanCatalog
dotnet new sln -n CleanCatalog
# Tạo các project Core
dotnet new classlib -n CleanCatalog.Domain
dotnet new classlib -n CleanCatalog.Application
# Tạo các project lớp ngoài
dotnet new classlib -n CleanCatalog.Infrastructure
dotnet new webapi -n CleanCatalog.Api --use-controllers
# Thêm các project vào solution
dotnet sln add CleanCatalog.Domain CleanCatalog.Application CleanCatalog.Infrastructure CleanCatalog.Api
# Thiết lập phụ thuộc hướng vào trong
dotnet add CleanCatalog.Application reference CleanCatalog.Domain
dotnet add CleanCatalog.Infrastructure reference CleanCatalog.Application
dotnet add CleanCatalog.Api reference CleanCatalog.Application
dotnet add CleanCatalog.Api reference CleanCatalog.Infrastructure
Cài đặt MediatR và EF Core vào các tầng tương ứng:
# MediatR v12+ cài đặt core contract và các extension cho DI
dotnet add CleanCatalog.Application package MediatR
# Lưu trữ cơ sở dữ liệu cho Infrastructure
dotnet add CleanCatalog.Infrastructure package Microsoft.EntityFrameworkCore.InMemory
# Phân giải MediatR trong host Presentation
dotnet add CleanCatalog.Api package MediatR
Bước 2: Định nghĩa Domain Entity
Xóa file Class1.cs trong CleanCatalog.Domain. Tạo một entity tự đóng gói (self-encapsulating) có tên là Product.cs:
namespace CleanCatalog.Domain.Entities;
public class Product
{
public Guid Id { get; private set; }
public string Name { get; private set; } = string.Empty;
public string Sku { get; private set; } = string.Empty;
public decimal Price { get; private set; }
public DateTime CreatedAtUtc { get; private set; }
private Product() { } // EF Core yêu cầu
public Product(string name, string sku, decimal price)
{
if (string.IsNullOrWhiteSpace(name))
throw new ArgumentException("Tên sản phẩm không được để trống.", nameof(name));
if (string.IsNullOrWhiteSpace(sku) || sku.Length < 3)
throw new ArgumentException("SKU phải chứa ít nhất 3 ký tự.", nameof(sku));
if (price <= 0.01m)
throw new ArgumentOutOfRangeException(nameof(price), "Giá phải từ $0.01 trở lên.");
Id = Guid.NewGuid();
Name = name.Trim();
Sku = sku.ToUpperInvariant().Trim();
Price = price;
CreatedAtUtc = DateTime.UtcNow;
}
}
Bước 3: Tạo các CQRS Handler trong tầng Application
Đầu tiên, định nghĩa repository contract trong CleanCatalog.Application/Common/Interfaces/IProductRepository.cs:
using CleanCatalog.Domain.Entities;
namespace CleanCatalog.Application.Common.Interfaces;
public interface IProductRepository
{
Task<Product?> GetByIdAsync(Guid id, CancellationToken cancellationToken);
Task AddAsync(Product product, CancellationToken cancellationToken);
}
Tiếp theo, triển khai command cùng handler tương ứng trong cùng một file CleanCatalog.Application/Products/Commands/CreateProduct/CreateProductCommand.cs:
using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Domain.Entities;
using MediatR;
namespace CleanCatalog.Application.Products.Commands.CreateProduct;
public record CreateProductCommand(string Name, string Sku, decimal Price) : IRequest<Guid>;
public class CreateProductCommandHandler : IRequestHandler<CreateProductCommand, Guid>
{
private readonly IProductRepository _repository;
public CreateProductCommandHandler(IProductRepository repository)
{
_repository = repository;
}
public async Task<Guid> Handle(CreateProductCommand request, CancellationToken cancellationToken)
{
var product = new Product(request.Name, request.Sku, request.Price);
await _repository.AddAsync(product, cancellationToken);
return product.Id;
}
}
Bây giờ, tạo query đọc dữ liệu trong CleanCatalog.Application/Products/Queries/GetProductById/GetProductByIdQuery.cs. Hãy chú ý cách handler trả về một DTO phẳng thay vì để lộ trực tiếp domain entity ra ngoài:
using CleanCatalog.Application.Common.Interfaces;
using MediatR;
namespace CleanCatalog.Application.Products.Queries.GetProductById;
public record ProductDto(Guid Id, string Name, string Sku, decimal Price, DateTime CreatedAtUtc);
public record GetProductByIdQuery(Guid Id) : IRequest<ProductDto?>;
public class GetProductByIdQueryHandler : IRequestHandler<GetProductByIdQuery, ProductDto?>
{
private readonly IProductRepository _repository;
public GetProductByIdQueryHandler(IProductRepository repository)
{
_repository = repository;
}
public async Task<ProductDto?> Handle(GetProductByIdQuery request, CancellationToken cancellationToken)
{
var product = await _repository.GetByIdAsync(request.Id, cancellationToken);
if (product is null) return null;
return new ProductDto(
product.Id,
product.Name,
product.Sku,
product.Price,
product.CreatedAtUtc);
}
}
Bước 4: Triển khai tầng Infrastructure với EF Core
Xây dựng logic lưu trữ dữ liệu bên trong CleanCatalog.Infrastructure/Persistence/AppDbContext.cs và ProductRepository.cs:
using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Domain.Entities;
using Microsoft.EntityFrameworkCore;
namespace CleanCatalog.Infrastructure.Persistence;
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
public DbSet<Product> Products => Set<Product>();
}
public class ProductRepository : IProductRepository
{
private readonly AppDbContext _context;
public ProductRepository(AppDbContext context)
{
_context = context;
}
public async Task AddAsync(Product product, CancellationToken cancellationToken)
{
await _context.Products.AddAsync(product, cancellationToken);
await _context.SaveChangesAsync(cancellationToken);
}
public async Task<Product?> GetByIdAsync(Guid id, CancellationToken cancellationToken)
{
return await _context.Products
.AsNoTracking()
.FirstOrDefaultAsync(p => p.Id == id, cancellationToken);
}
}
Bước 5: Viết các Controller tinh gọn
Nhiệm vụ của controller chỉ đơn thuần là chuyển đổi HTTP request thành application message, không hơn không kém. Thêm ProductsController.cs vào thư mục CleanCatalog.Api/Controllers:
using CleanCatalog.Application.Products.Commands.CreateProduct;
using CleanCatalog.Application.Products.Queries.GetProductById;
using MediatR;
using Microsoft.AspNetCore.Mvc;
namespace CleanCatalog.Api.Controllers;
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
private readonly ISender _sender;
public ProductsController(ISender sender)
{
_sender = sender;
}
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create([FromBody] CreateProductCommand command, CancellationToken ct)
{
var productId = await _sender.Send(command, ct);
return CreatedAtAction(nameof(GetById), new { id = productId }, new { id = productId });
}
[HttpGet("{id:guid}")]
[ProducesResponseType(typeof(ProductDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
{
var result = await _sender.Send(new GetProductByIdQuery(id), ct);
return result is not null ? Ok(result) : NotFound();
}
}
Bước 6: Đăng ký dịch vụ trong Program.cs
Mở CleanCatalog.Api/Program.cs và cấu hình các service vào dependency injection container của .NET 9:
using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Application.Products.Commands.CreateProduct;
using CleanCatalog.Infrastructure.Persistence;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
// Sử dụng in-memory database để test cục bộ
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("CatalogDb"));
builder.Services.AddScoped<IProductRepository, ProductRepository>();
// Đăng ký các MediatR handler từ assembly Application
builder.Services.AddMediatR(cfg =>
cfg.RegisterServicesFromAssembly(typeof(CreateProductCommand).Assembly));
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
Khởi động API bằng lệnh dotnet run --project CleanCatalog.Api. Truy cập vào địa chỉ https://localhost:5001/swagger. Gửi một request POST với body {"name": "Mechanical Keyboard", "sku": "KB-980", "price": 129.99}. Bạn sẽ nhận được mã phản hồi 201 Created chỉ trong khoảng 15ms. Controller hoàn toàn không chứa logic phức tạp, trong khi business rule của domain vẫn đảm bảo dữ liệu luôn hợp lệ.
Các bước tiếp theo
Mô hình kiến trúc này mang lại sự phân tách rạch ròi giữa các tầng. Khi sản phẩm của bạn mở rộng từ 2 endpoint lên 150 endpoint, bạn chỉ việc tạo thêm các command và query record mới mà không cần chạm vào các handler hiện có. Ngoài ra, bên cạnh việc phân tầng theo Clean Architecture, bạn cũng có thể cân nhắc áp dụng Vertical Slice Architecture trong dự án ASP.NET Core để tổ chức mã nguồn trực tiếp theo từng lát cắt tính năng.
Từ nền tảng này, bạn có thể bổ sung các MediatR pipeline behavior để xử lý các vấn đề mang tính tổng thể (cross-cutting concerns) như kiểm tra dữ liệu đầu vào (bằng FluentValidation) hay ghi log hiệu năng tại một nơi duy nhất. Khi lưu lượng đọc tăng đột biến, bạn chỉ cần thay thế ProductRepository.GetByIdAsync bằng một truy vấn Dapper thuần hoặc lấy từ Redis cache. Tầng Presentation sẽ không nhận thấy bất kỳ sự khác biệt nào.

