Sử Dụng FluentValidation Để Kiểm Soát Đầu Vào Hiệu Quả trên Chặng Đường Lộ Trình .NET

DataAnnotations trả lời được câu “trường này có rỗng không”. Nó không trả lời được “mã khách hàng này có tồn tại không”, “ngày giao có sau hôm nay không khi phương thức là hẹn giờ”, hay “tổng tiền các dòng có khớp không”. FluentValidation giải quyết phần đó — nhưng từ phiên bản 11, nó không còn tự động chạy khi model binding, và đó là lý do nhiều project nâng cấp xong thấy validation “im lặng”.

Cập nhật 2026

  • FluentValidation 12.2.0, giấy phép Apache-2.0, vẫn là lựa chọn phổ biến nhất cho rule phức tạp.
  • Auto-validation đã bị bỏ từ v11. AddFluentValidationAutoValidation() và package FluentValidation.AspNetCore không còn là cách tích hợp hiện hành. Bạn validate tường minh hoặc dùng endpoint filter.
  • ASP.NET Core 10 có validation tích hợp cho Minimal API: builder.Services.AddValidation() chạy DataAnnotations và IValidatableObject, trả 400 ProblemDetails tự động. FluentValidation vì thế là lựa chọn, không phải mặc định bắt buộc.
  • CascadeMode mặc định của cả class và rule là Continue — rule đầu fail không chặn các rule sau. Nếu bạn muốn dừng sớm, phải đặt tường minh.

Khi nào DataAnnotations là đủ

Tình huống Chọn
DTO đơn giản: required, độ dài, range, regex, email DataAnnotations + AddValidation(). Ít code nhất, không thêm dependency.
Rule phụ thuộc nhiều trường, phụ thuộc DB, hoặc khác nhau theo ngữ cảnh create/update FluentValidation. Attribute không inject được service và không đọc được dữ liệu ngoài.
Cần unit test rule độc lập, message theo resource, error code cho client FluentValidation. TestValidate và WithErrorCode cho bạn điều đó.
Domain model thuần, không muốn ràng buộc UI vào entity FluentValidation ở tầng Application, không đặt attribute lên entity.

Nguyên tắc chọn: theo từng DTO, không theo cả project. Một project có thể dùng DataAnnotations cho 80% DTO CRUD và FluentValidation cho 20% DTO có rule nghiệp vụ. Việc trộn hai cơ chế trong cùng một DTO mới là thứ gây khó chịu, không phải việc trộn trong cùng project.

Cài đặt đúng package

dotnet add package FluentValidation --version 12.2.0
dotnet add package FluentValidation.DependencyInjectionExtensions --version 12.2.0

Gói thứ hai chỉ chứa AddValidatorsFromAssembly. Đừng cài FluentValidation.AspNetCore — đó là tích hợp của thời MVC với auto-validation, đã lỗi thời và dễ kéo theo hành vi bạn không kiểm soát.

// File: Program.cs
builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>(
    ServiceLifetime.Scoped);

Scoped, không phải Singleton. Validator thường inject DbContext hoặc repository scoped; đăng ký singleton sẽ tạo captive dependency và lỗi “DbContext disposed” chỉ xuất hiện dưới tải. Vòng đời DI đã bàn kỹ ở bài về Scoped, Transient, Singleton.

Validator đầu tiên

// File: Features/Orders/CreateOrderValidator.cs
using FluentValidation;

public sealed class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderValidator(IOrderRepository repository, TimeProvider clock)
    {
        ClassLevelCascadeMode = CascadeMode.Stop;
        RuleLevelCascadeMode = CascadeMode.Continue;

        RuleFor(x => x.CustomerId)
            .NotEmpty().WithMessage("Mã khách hàng không được để trống.")
            .MaximumLength(32)
            .MustAsync((id, ct) => repository.CustomerExistsAsync(id, ct))
                .WithMessage("Khách hàng không tồn tại.")
                .WithErrorCode("customer_not_found")
                .When(x => !string.IsNullOrWhiteSpace(x.CustomerId));

        RuleFor(x => x.Items)
            .NotEmpty().WithMessage("Đơn hàng phải có ít nhất một dòng.")
            .Must(items => items.Count <= 200)
                .WithMessage("Một đơn tối đa 200 dòng.");

        RuleForEach(x => x.Items).SetValidator(new OrderLineValidator());

        RuleFor(x => x.ScheduledFor)
            .GreaterThan(_ => clock.GetUtcNow().UtcDateTime)
            .WithMessage("Thời điểm giao phải ở tương lai.")
            .When(x => x.DeliveryMethod == DeliveryMethod.Scheduled);

        RuleFor(x => x.Note)
            .MaximumLength(500)
            .Must(note => note is null || !note.Contains("--"))
                .WithMessage("Ghi chú không được chứa chuỗi '--'.");
    }
}

Ba điểm đáng chú ý. Thứ nhất, ClassLevelCascadeMode = CascadeMode.Stop nghĩa là nếu rule của CustomerId fail, các rule của trường khác vẫn chạy — nó chỉ dừng các rule trong cùng một RuleFor khi rule đầu fail. Thứ hai, .When(...) gắn điều kiện cho toàn bộ chuỗi phía trước, nên NotEmpty vẫn chạy trước khi kiểm tra DB. Thứ ba, MustAsync nhận CancellationToken từ ValidateAsync — nếu bạn gọi Validate đồng bộ, FluentValidation ném AsyncValidatorInvokedSynchronouslyException, không phải chạy “kiểu gì cũng được”.

Rule tùy biến và rule phức tạp

Must đủ cho phần lớn trường hợp. Khi cần truy cập cả object hoặc thêm nhiều lỗi cùng lúc, dùng Custom hoặc CustomAsync:

RuleFor(x => x).CustomAsync(async (request, context, ct) =>
{
    var total = request.Items.Sum(i => i.Quantity * i.UnitPrice);
    if (total <= 0)
    {
        context.AddFailure(nameof(request.Items), "Tổng tiền phải lớn hơn 0.");
    }

    var duplicated = request.Items
        .GroupBy(i => i.Sku)
        .Where(g => g.Count() > 1)
        .Select(g => g.Key);

    foreach (var sku in duplicated)
    {
        context.AddFailure(nameof(request.Items), $"SKU {sku} bị lặp.");
    }

    await Task.CompletedTask;
});

context.AddFailure(propertyName, message) cho phép gắn lỗi vào một property cụ thể, và mỗi lần gọi là một lỗi riêng — khác với Must chỉ trả về một message. Đừng lạm dụng: nếu một rule cần 5 lỗi chi tiết, hãy tách thành 5 rule nhỏ để client hiển thị đúng chỗ.

Đối tượng lồng nhau và collection dùng SetValidator như trong ví dụ trên. Validator con có thể được inject qua constructor nếu nó cần service; SetValidator(new OrderLineValidator()) chỉ ổn khi validator con không phụ thuộc gì. Với validator con cần DI, inject IValidator<OrderLine> vào validator cha rồi truyền vào SetValidator — AddValidatorsFromAssembly đã đăng ký sẵn.

Tích hợp ASP.NET Core 10: validate tường minh

Vì không còn auto-validation, hãy chọn một trong hai cách: gọi validator trong handler, hoặc dùng endpoint filter dùng chung. Endpoint filter là cách gọn nhất cho Minimal API.

// File: Infrastructure/ValidationEndpointFilter.cs
using FluentValidation;

public static class ValidationEndpointFilterExtensions
{
    public static RouteHandlerBuilder WithFluentValidation<T>(this RouteHandlerBuilder builder)
        where T : class
    {
        return builder.AddEndpointFilter(async (context, next) =>
        {
            var validator = context.HttpContext.RequestServices
                .GetRequiredService<IValidator<T>>();

            if (context.Arguments.OfType<T>().FirstOrDefault() is not { } model)
            {
                return TypedResults.ValidationProblem(new Dictionary<string, string[]>
                {
                    ["body"] = ["Request body không hợp lệ."],
                });
            }

            var result = await validator.ValidateAsync(model, context.HttpContext.RequestAborted);

            return result.IsValid
                ? await next(context)
                : TypedResults.ValidationProblem(result.ToDictionary());
        });
    }
}
// File: Endpoints/OrderEndpoints.cs
var orders = app.MapGroup("/api/orders");

orders.MapPost("/", async (
        CreateOrderRequest request,
        IOrderService service,
        CancellationToken ct) =>
        TypedResults.Ok(await service.CreateAsync(request, ct)))
    .WithFluentValidation<CreateOrderRequest>();

result.ToDictionary() là extension của FluentValidation, trả về Dictionary<string, string[]> đúng shape của ValidationProblemDetails.errors. Client nhận 400 với application/problem+json, có errors.CustomerId[0] và errors.Items[0]. Đừng trả BadRequest(result.Errors): nó serialize cả object ValidationFailure, lộ tên type nội bộ và không theo chuẩn RFC 9457.

Nếu DTO của bạn chỉ có DataAnnotations, hãy dùng validation tích hợp: builder.Services.AddValidation() rồi khai báo [Required], [Range] trên record. Hai cơ chế có thể sống cùng, nhưng đừng đặt cùng một rule ở cả hai nơi — client sẽ nhận hai message cho một lỗi.

ValidationProblemDetails và lỗi nghiệp vụ

Có hai loại lỗi khác nhau: lỗi hình thức (400, client sửa được) và lỗi nghiệp vụ (409/422, phải đổi trạng thái hệ thống). FluentValidation giỏi loại thứ nhất. Với loại thứ hai — ví dụ “đơn đã được duyệt nên không sửa được” — hãy ném domain exception và map ở middleware, đừng nhồi vào validator. Validator chạy trước khi handler thực thi; nó không có quyền đọc trạng thái nghiệp vụ đã thay đổi trong transaction.

Cũng đừng dùng validator như nơi ghi log hoặc gọi API ngoài. Một MustAsync gọi HTTP trong mỗi request là cách nhanh nhất để thêm 200ms vào latency toàn hệ thống, và nó chạy cả khi request sẽ fail vì lý do khác.

Localization

Message mặc định của FluentValidation là tiếng Anh. Đặt ValidatorOptions.Global.LanguageManager.Culture sang vi-VN không tự dịch message — bộ message built-in chỉ có tiếng Anh. Hai cách thực dụng:

  • Viết WithMessage với chuỗi lấy từ resource (IStringLocalizer, .resx) ngay trong validator. Đây là cách đơn giản nhất và kiểm soát được toàn bộ nội dung.
  • Cung cấp ILanguageManager riêng nếu bạn muốn dùng lại message cho mọi validator, nhưng phải map đủ key cho các rule đang dùng.

Đừng trộn: một nửa message tiếng Anh, một nửa tiếng Việt trong cùng response là lỗi QA rất dễ lọt.

Test validator

// File: Tests/CreateOrderValidatorTests.cs
using FluentValidation.TestHelper;

public sealed class CreateOrderValidatorTests
{
    private readonly CreateOrderValidator _validator =
        new(new StubRepository(customerExists: false), TimeProvider.System);

    [Fact]
    public async Task Fails_when_customer_does_not_exist()
    {
        var request = new CreateOrderRequest
        {
            CustomerId = "C-404",
            Items = [new OrderLine { Sku = "SKU-1", Quantity = 1, UnitPrice = 10m }],
            DeliveryMethod = DeliveryMethod.Standard,
        };

        var result = await _validator.TestValidateAsync(request);

        result.ShouldHaveValidationErrorFor(x => x.CustomerId)
              .WithErrorCode("customer_not_found");
    }

    [Fact]
    public async Task Passes_for_valid_order()
    {
        var request = new CreateOrderRequest
        {
            CustomerId = "C-1",
            Items = [new OrderLine { Sku = "SKU-1", Quantity = 2, UnitPrice = 5m }],
        };

        var result = await _validator.TestValidateAsync(request);
        result.ShouldNotHaveAnyValidationErrors();
    }
}

Phải dùng TestValidateAsync khi validator có rule async. TestValidate chỉ chạy được rule đồng bộ và sẽ ném exception với MustAsync. Đây là lỗi rất hay gặp khi copy test mẫu từ blog cũ.

Viết validator như POCO: constructor nhận dependency, không đọc static, không phụ thuộc HttpContext. Như vậy test không cần web host, chỉ cần fake repository — nhanh và ổn định. Nếu bạn phải dựng cả WebApplicationFactory để test một rule độc lập, validator đang bị trói vào tầng web.

Validate ngoài HTTP

Worker, background job hay import CSV không đi qua endpoint filter. Ở đó bạn inject IValidator<T> và gọi tường minh; ValidationException giữ nguyên danh sách ValidationFailure để tầng trên map sang problem details nếu cần.

// File: Orders/OrderImportJob.cs
var result = await _validator.ValidateAsync(dto, ct);
if (!result.IsValid)
{
    throw new ValidationException(result.Errors);
}

Với batch lớn, đừng validate từng item rồi throw ngay ở item đầu: gom lỗi theo index để người vận hành thấy cả file hỏng ở đâu, thay vì sửa một dòng rồi chạy lại.

RuleSets: một validator, nhiều ngữ cảnh

Khi create và update dùng chung DTO, đừng viết hai validator gần giống nhau. RuleSets nhóm rule theo tên, nhưng rule trong RuleSet không chạy mặc định — bạn phải gọi IncludeRuleSets("Create"). Với Minimal API, truyền tên rule set qua endpoint filter để giữ một nguồn rule duy nhất.

Endpoint filter chạy sau model binding và trước handler: DTO đã deserialize, chưa có side effect nào. Nếu bạn đăng ký nhiều filter, chúng chạy theo thứ tự đăng ký — đặt validation sớm nhất để request invalid không tốn query của các filter khác.

Anti-pattern

  • Validator “vạn năng” cho mọi ngữ cảnh create/update/import. Tách DTO hoặc dùng RuleSets, và nhớ RuleSets chỉ chạy khi bạn gọi IncludeRuleSets.
  • Tin vào auto-validation cũ. Không có filter thì không có gì chạy; test end-to-end một request invalid là cách duy nhất để chắc chắn.
  • Validate sau khi đã ghi DB. Validation phải chặn trước side effect, không phải sau.
  • Throw exception trong validator để “báo lỗi”. Trả ValidationResult, để tầng API quyết định status code.
  • Đặt validator trong Domain layer nhưng inject repository. Đó là phụ thuộc ngược; giữ validator ở Application.

Checklist

  • Cài FluentValidation + DependencyInjectionExtensions 12.2.0, không cài FluentValidation.AspNetCore.
  • Đăng ký AddValidatorsFromAssemblyContaining với ServiceLifetime.Scoped.
  • Đặt ClassLevelCascadeMode/RuleLevelCascadeMode tường minh nếu cần dừng sớm.
  • Dùng endpoint filter để trả ValidationProblemDetails cho mọi Minimal API group.
  • Test async rule bằng TestValidateAsync.
  • Kiểm tra DTO nào đang dùng DataAnnotations để không chạy hai lớp rule trùng nhau.

Đọc tiếp