C#怎么使用FluentValidation实现优雅的实体属性校验规则

在C#项目开发中，实体属性校验是数据进入业务逻辑前的必要环节，传统的基于特性的校验方式在面对复杂校验逻辑时显得不够灵活，而FluentValidation提供了链式配置的校验方式，让校验规则的定义更清晰、更易维护。

FluentValidation基础使用步骤

1. 安装依赖包

首先需要通过NuGet安装FluentValidation包，在Visual Studio的包管理器控制台执行以下命令：

Install-Package FluentValidation

2. 定义待校验的实体类

先创建一个简单的用户实体类，包含需要校验的属性：

public class User
{
    public string UserName { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
    public Address Address { get; set; }
}

public class Address
{
    public string Province { get; set; }
    public string City { get; set; }
}

3. 创建校验器类

校验器类需要继承AbstractValidator<T>泛型类，其中T为待校验的实体类型，在校验器构造函数中定义具体的校验规则：

using FluentValidation;

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        // 用户名校验：非空，长度2-20位
        RuleFor(user => user.UserName)
            .NotEmpty().WithMessage("用户名不能为空")
            .Length(2, 20).WithMessage("用户名长度必须在2到20位之间");

        // 邮箱校验：非空，符合邮箱格式
        RuleFor(user => user.Email)
            .NotEmpty().WithMessage("邮箱不能为空")
            .EmailAddress().WithMessage("邮箱格式不正确");

        // 年龄校验：大于等于18，小于等于60
        RuleFor(user => user.Age)
            .InclusiveBetween(18, 60).WithMessage("年龄必须在18到60岁之间");
    }
}

4. 执行校验逻辑

创建实体实例后，实例化校验器并调用Validate方法即可完成校验，校验结果包含是否通过、错误信息等内容：

class Program
{
    static void Main(string[] args)
    {
        var user = new User
        {
            UserName = "张三",
            Email = "zhangsan@ippipp.com",
            Age = 25
        };

        var validator = new UserValidator();
        var validationResult = validator.Validate(user);

        if (validationResult.IsValid)
        {
            Console.WriteLine("实体校验通过");
        }
        else
        {
            foreach (var error in validationResult.Errors)
            {
                Console.WriteLine($"属性{error.PropertyName}校验失败：{error.ErrorMessage}");
            }
        }
    }
}

进阶校验场景

自定义校验逻辑

当内置的校验规则无法满足需求时，可以使用Must方法自定义校验逻辑：

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        // 自定义校验：用户名不能包含特殊字符
        RuleFor(user => user.UserName)
            .Must(userName => !userName.Any(c => !char.IsLetterOrDigit(c)))
            .WithMessage("用户名不能包含特殊字符");
    }
}

嵌套实体校验

如果实体包含子实体属性，可以通过SetValidator方法关联子实体的校验器：

public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(addr => addr.Province).NotEmpty().WithMessage("省份不能为空");
        RuleFor(addr => addr.City).NotEmpty().WithMessage("城市不能为空");
    }
}

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        // 关联地址校验器
        RuleFor(user => user.Address).SetValidator(new AddressValidator());
    }
}

条件校验

可以使用When方法设置校验规则生效的条件：

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        // 当年龄大于等于18时，才校验邮箱必填
        RuleFor(user => user.Email)
            .NotEmpty().WithMessage("成年用户邮箱不能为空")
            .When(user => user.Age >= 18);
    }
}

校验规则复用

如果有多个实体需要相同的校验规则，可以定义通用的校验规则扩展方法：

public static class ValidatorExtensions
{
    public static IRuleBuilderOptions<T, string> PhoneNumberRule<T>(this IRuleBuilder<T, string> ruleBuilder)
    {
        return ruleBuilder
            .NotEmpty().WithMessage("手机号不能为空")
            .Matches(@"^1[3-9]d{9}$").WithMessage("手机号格式不正确");
    }
}

public class UserValidator : AbstractValidator<User>
{
    public UserValidator()
    {
        // 复用手机号校验规则
        RuleFor(user => user.PhoneNumber).PhoneNumberRule();
    }
}

常见内置校验规则汇总

以下是FluentValidation常用的内置校验规则说明：

C#FluentValidation实体属性校验校验规则修改时间：2026-07-22 10:18:31