Kiến Trúc Sạch (Clean Architecture) trong ASP.NET Core: Giới Thiệu Thực Chiến

Kiến trúc sạch (Clean Architecture) không làm code của bạn đẹp hơn. Nó làm đúng một việc: buộc mọi phụ thuộc giữa các tầng chỉ trỏ theo một hướng, để khi bạn đổi database, đổi giao diện hay đổi framework web, phần logic nghiệp vụ vẫn đứng yên. Đổi lại, bạn trả bằng số project, số interface và một vòng suy nghĩ dài hơn cho mỗi tính năng mới. Vấn đề là nhiều team trả giá mà không nhận được gì, vì họ copy cấu trúc thư mục chứ không cưỡng chế được ranh giới.

Cập nhật 2026

  • Bản production hiện tại là .NET 10 LTS (10.0.14); .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 và C# 14.
  • MediatR 14.3.0 nằm dưới giấy phép thương mại từ v13, nên bài dùng handler tự viết trong Application layer thay vì mặc định gắn mediator.
  • Vertical Slice Architecture là đối trọng phổ biến năm 2026 cho các ứng dụng CRUD-heavy; có bảng so sánh ở cuối bài.

Dependency Rule: một câu, compiler kiểm tra được

Quy tắc phụ thuộc nói gọn: mã ở vòng trong không được biết gì về mã ở vòng ngoài. Domain không biết EF Core tồn tại. Application không biết bạn dùng SQL Server, PostgreSQL hay một message broker. Presentation không biết bảng nào có cột nào.

Điểm hay bị hiểu sai: “không biết” ở đây là không biết lúc compile. Application được phép nhận một IOrderRepository qua constructor, miễn interface đó do chính Application định nghĩa. Ai cài đặt nó và cài đặt bằng gì là việc của composition root. DI giải quyết phụ thuộc lúc runtime, project reference giải quyết lúc compile; hai thứ phải khớp nhau, và khi lệch nhau thì bạn có một dependency ảo.

Tầng Chứa gì Được tham chiếu
Domain Entity, value object, domain event, exception nghiệp vụ Không project nào trong solution
Application Use case handler, port (interface), DTO vào/ra Domain
Infrastructure EF Core, repository adapter, HTTP client, email, outbox Application
Presentation Endpoint, request/response model, DI, auth Application + Infrastructure, chỉ ở Program.cs

Chú ý dòng cuối: Presentation tham chiếu Infrastructure chỉ để gọi extension method đăng ký DI. Không endpoint nào được inject trực tiếp ShopDbContext. Nếu bạn thấy điều đó trong code review, ranh giới đã thủng và mọi thứ sau đó chỉ còn là hình thức.

Cấu trúc thư mục thực dụng

Đừng dựng bốn project cho một API ba endpoint. Nhưng khi đã dựng thì đặt tên theo việc, không theo tầng kỹ thuật:

src/
  Shop.Domain/            Orders/Order.cs, Money.cs, OrderSubmitted.cs
  Shop.Application/       Orders/CreateOrder.cs, Ports/IOrderRepository.cs
  Shop.Infrastructure/    Persistence/ShopDbContext.cs, OrderRepository.cs
  Shop.Api/               Program.cs, Endpoints/OrdersEndpoints.cs
tests/
  Shop.Domain.Tests/
  Shop.Application.Tests/
  Shop.IntegrationTests/

Hai chi tiết đáng chú ý. Orders/ nằm trong Application chứ không tách Commands/ và Queries/: gom theo use case để mở một thư mục là thấy cả luồng. Và không có project Shop.Shared hay Shop.Contracts — đó thường là nơi mọi thứ không biết đặt đâu bị tống vào, rồi vài tháng sau nó tham chiếu ngược lại Infrastructure và phá vỡ mô hình.

Ranh giới phải được cưỡng chế

Project reference là một dòng trong .csproj; ai cũng thêm được lúc vội. Viết test kiến trúc chạy trong CI để luật không phụ thuộc vào trí nhớ của người review:

// File: tests/Shop.Domain.Tests/LayerTests.cs
using System.Reflection;
using Xunit;

public class LayerTests
{
    [Fact]
    public void Domain_khong_tham_chieu_project_nao_khac()
    {
        var refs = typeof(Order).Assembly.GetReferencedAssemblies()
            .Select(a => a.Name)
            .Where(n => n!.StartsWith("Shop."));

        Assert.Empty(refs);
    }

    [Fact]
    public void Application_khong_tham_chieu_EF_Core()
    {
        var refs = typeof(CreateOrder).Assembly.GetReferencedAssemblies()
            .Select(a => a.Name);

        Assert.DoesNotContain("Microsoft.EntityFrameworkCore", refs);
    }
}

Test này bắt đúng lỗi hay gặp nhất: một dev thêm using Microsoft.EntityFrameworkCore; vào Application để dùng Include cho nhanh. Nó cũng là tài liệu sống — người mới đọc file test hiểu ngay luật của repo. Chạy bằng dotnet test trên Microsoft.Testing.Platform của .NET 10, không cần cấu hình thêm.

Use case handler: đơn vị công việc, không phải service “mập”

Mỗi use case là một lớp, một phương thức public, một quyết định. Handler điều phối: lấy aggregate, gọi hành vi miền, lưu, commit. Nó không chứa quy tắc nghiệp vụ — nếu bạn thấy điều kiện về trạng thái đơn hàng trong handler, logic đó phải nằm trong entity.

// File: src/Shop.Application/Orders/CreateOrder.cs
public sealed record CreateOrder(Guid CustomerId, IReadOnlyList<OrderLineInput> Lines);

public sealed record OrderLineInput(string Sku, decimal UnitPrice, int Quantity);

public interface ICreateOrderHandler
{
    Task<Guid> HandleAsync(CreateOrder command, CancellationToken ct);
}

public sealed class CreateOrderHandler(IOrderRepository orders, IUnitOfWork unitOfWork)
    : ICreateOrderHandler
{
    public async Task<Guid> HandleAsync(CreateOrder command, CancellationToken ct)
    {
        var lines = command.Lines.Select(l => new OrderLine(l.Sku, l.UnitPrice, l.Quantity));
        var order = Order.Create(command.CustomerId, lines);

        await orders.AddAsync(order, ct);
        await unitOfWork.CommitAsync(ct);
        return order.Id;
    }
}

IOrderRepository và IUnitOfWork được định nghĩa trong Application, không phải Infrastructure. Đó là toàn bộ ý nghĩa của port: hình dạng hợp đồng do tầng trong quyết định, tầng ngoài chỉ có quyền thực hiện.

// File: src/Shop.Application/DependencyInjection.cs
public static IServiceCollection AddApplication(this IServiceCollection services)
{
    services.AddScoped<ICreateOrderHandler, CreateOrderHandler>();
    services.AddScoped<IGetOrderHandler, GetOrderHandler>();
    return services;
}

Endpoint chỉ biết interface, không biết lớp cài đặt:

// File: src/Shop.Api/Endpoints/OrdersEndpoints.cs
app.MapPost("/orders", async (CreateOrder command, ICreateOrderHandler handler, CancellationToken ct) =>
{
    var id = await handler.HandleAsync(command, ct);
    return TypedResults.Created($"/orders/{id}", id);
});

Nếu team đã mua license MediatR 14.3.0, bạn thay ICreateOrderHandler bằng IRequest<Guid> cộng IRequestHandler<CreateOrder, Guid> mà không đổi phần còn lại. Đừng thêm MediatR chỉ vì “Clean Architecture phải có mediator” — nó là dependency thương mại, không phải thành phần của mô hình.

Ports and adapters

Port là interface ở tầng trong; adapter là cài đặt ở tầng ngoài. Adapter không được rò kiểu EF Core ra ngoài — không trả IQueryable<T>, không trả DbSet<T>. Nếu Application nhận IQueryable, bạn vừa chuyển quyền quyết định truy vấn sang tầng ngoài và mất luôn khả năng test handler mà không cần database.

// File: src/Shop.Application/Ports/IOrderRepository.cs
public interface IOrderRepository
{
    Task AddAsync(Order order, CancellationToken ct);
    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct);
}
// File: src/Shop.Infrastructure/Persistence/OrderRepository.cs
internal sealed class OrderRepository(ShopDbContext db) : IOrderRepository
{
    public Task AddAsync(Order order, CancellationToken ct)
        => db.Orders.AddAsync(order, ct).AsTask();

    public Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
        => db.Orders.FirstOrDefaultAsync(o => o.Id == id, ct);
}

Mapping đặt ở Infrastructure, không ở Domain:

// File: src/Shop.Infrastructure/Persistence/OrderConfiguration.cs
internal sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");
        builder.HasKey(o => o.Id);
        builder.OwnsMany(o => o.Lines, lines =>
        {
            lines.ToTable("OrderLines");
            lines.WithOwner().HasForeignKey("OrderId");
            lines.Property(l => l.Sku).HasMaxLength(64).IsRequired();
            lines.Property(l => l.UnitPrice).HasPrecision(18, 2);
        });
        builder.Navigation(o => o.Lines).UsePropertyAccessMode(PropertyAccessMode.Field);
    }
}

UsePropertyAccessMode(PropertyAccessMode.Field) cho EF Core ghi thẳng vào backing field _lines thay vì gọi setter, đúng thứ bạn cần khi collection chỉ đọc. Chi tiết này hay bị bỏ qua và là nguồn của lỗi “collection null sau khi load”.

Kiểm thử ở ranh giới

Ranh giới chia test thành hai loại. Unit test cho domain và handler dùng fake port — nhanh, không database, chạy hàng nghìn test trong vài giây. Integration test cho adapter và endpoint dùng WebApplicationFactory 10.0.14 với Testcontainers 4.16 và Respawn 7 — chậm hơn nhưng bắt được lỗi dịch LINQ, migration và serialization.

// File: tests/Shop.Application.Tests/CreateOrderHandlerTests.cs
[Fact]
public async Task Tao_don_va_commit_dung_mot_lan()
{
    var orders = Substitute.For<IOrderRepository>();
    var uow = Substitute.For<IUnitOfWork>();
    var handler = new CreateOrderHandler(orders, uow);

    var id = await handler.HandleAsync(
        new CreateOrder(Guid.NewGuid(), [new OrderLineInput("SKU-1", 25m, 2)]), default);

    await orders.Received(1).AddAsync(Arg.Is<Order>(o => o.Id == id), Arg.Any<CancellationToken>());
    await uow.Received(1).CommitAsync(Arg.Any<CancellationToken>());
}

Đừng mock DbContext. Nếu bạn phải mock nó, nghĩa là handler đang phụ thuộc trực tiếp vào EF Core — sửa thiết kế, đừng sửa test. Còn adapter EF Core thì phải test bằng database thật trong container, vì thứ duy nhất bạn cần kiểm chứng là câu SQL sinh ra đúng và mapping không làm mất dữ liệu.

Năm cái bẫy thật

  • Anemic domain model. Entity toàn public set, không phương thức, mọi logic nằm trong handler. Bạn có đủ bốn project nhưng phần “domain” chỉ là bảng ánh xạ. Dấu hiệu: mở một entity ra không thấy hành vi nào.
  • Bùng nổ DTO. Mỗi request có ba lớp cho chiều vào và ba lớp cho chiều ra; sửa một trường phải đi qua sáu file. Giữ hai lớp — request/response ở Presentation, command/query ở Application — và map một lần.
  • Interface hóa mọi thứ. ICustomerService chỉ có một cài đặt và không bao giờ bị thay. Interface chỉ đáng tồn tại khi có ít nhất hai cài đặt thật, hoặc khi nó là port ở ranh giới tầng.
  • “Clean” nhưng chậm. Repository trả aggregate, handler map sang DTO, API map lần nữa; query đọc 20 cột để dùng 3; N+1 vì mỗi aggregate load một collection. Kiến trúc không gây ra hiệu năng kém, nhưng nó che giấu chi phí — hãy đo bằng log SQL và BenchmarkDotNet 0.15.8 trước khi tối ưu.
  • Layer cake. Controller gọi Service gọi Repository gọi DbContext, mỗi tầng chỉ chuyển tiếp tham số. Đó là nghi thức, không phải kiến trúc. Nếu một lớp không ra quyết định gì, xóa nó.

Clean Architecture và Vertical Slice

Vertical Slice tổ chức theo tính năng: một thư mục chứa endpoint, handler, query và mapping cho đúng một use case, xuyên qua các tầng kỹ thuật. Clean Architecture tổ chức theo tầng: mọi thứ cùng loại nằm cạnh nhau. Hai cách trả lời hai câu hỏi khác nhau.

Tiêu chí Clean Architecture Vertical Slice
Câu hỏi trung tâm “Cái này thuộc tầng nào?” “Cái này phục vụ tính năng nào?”
CRUD nhiều, ít logic Nhiều ma sát, nhiều lớp trung gian Ít ma sát, thêm tính năng nhanh
Logic miền phức tạp Domain độc lập, dễ test sâu Dễ trùng lặp quy tắc giữa các slice
Onboarding Cần hiểu luật phụ thuộc trước Đọc một slice là hiểu một luồng

Kết luận thực dụng: với hệ thống có miền phức tạp, Clean Architecture thắng vì domain là tài sản dài hạn. Với API CRUD và team nhỏ, mỗi tính năng một thư mục thường rẻ hơn và ít lớp trung gian hơn. Đừng chọn theo blog; chọn theo độ phức tạp của nghiệp vụ và tuổi thọ dự kiến của hệ thống.

Khi nào không nên dùng

Bỏ qua khi ứng dụng là CRUD thuần và sẽ sống dưới một năm, hoặc khi team chưa từng vận hành mô hình này và deadline tính bằng tuần. Bốn project với ba endpoint là chi phí thuần túy: thêm file, thêm build, thêm chỗ để sai.

  • Hệ thống nội bộ ít người dùng, ít thay đổi, không có kế hoạch thay database hay framework.
  • Team dưới ba người và không ai review được ranh giới một cách nghiêm túc.
  • Bạn chưa có test — ranh giới không có test chỉ là quy ước trên giấy.

Nếu vẫn muốn giữ nguyên tắc, hãy áp dụng Dependency Inversion trong một project duy nhất bằng folder và namespace. Nâng lên multi-project khi có lý do cụ thể: cần đóng gói domain cho client khác, cần chặn một nhóm dev sửa persistence, hoặc cần build nhanh hơn bằng cách cắt bớt project.

Checklist và hướng 2027

  • Vẽ bảng phụ thuộc ra giấy trước khi tạo project; nếu có mũi tên ngược chiều, dừng lại.
  • Thêm test kiến trúc vào CI ngay ngày đầu, không phải sau khi đã có 40 project.
  • Mỗi handler một use case; mỗi entity tự bảo vệ invariant của nó.
  • Đo trước khi tối ưu: bật log SQL, chạy BenchmarkDotNet 0.15.8 ở chế độ Release.

Năm 2027, .NET 12 LTS dự kiến ra mắt và .NET 11 (GA tháng 11/2026) là bản STS hai năm. Không có API kiến trúc nào thay đổi; thứ thay đổi là chi phí license của các thư viện tiện ích và việc AI-assisted refactor làm cho việc tách project rẻ hơn về công sức, nhưng không rẻ hơn về quyết định thiết kế.

Đọc tiếp trong series