FluentValidation 入门指南：基于强类型规则的 .NET 校验体系构建与源码原理解析

后端【免费下载链接】FluentValidationA popular .NET validation library for building strongly-typed validation rules.项目地址https://gitcode.com/gh_mirrors/fl/FluentValidation点击查看免费下载导读FluentValidation 是一个 .NET 校验库核心思想是「用强类型的流畅接口Fluent Interface为对象构建校验规则」从而让校验逻辑可读、可维护、可测试。本文以官方文档首页 docs/index.rst 与入门文档 docs/start.md 为主线完整覆盖从安装、创建第一个验证器、运行校验、读取结果到链式校验、异常抛出、复杂属性复用等全部入门内容并对照仓库源码如 src/FluentValidation/AbstractValidator.cs、src/FluentValidation/Results/ValidationResult.cs讲解底层原理。读完本文你将能独立为一个业务对象编写完整验证器并理解校验结果与异常机制的真实行为。项目定位强类型校验规则引擎docs/index.rst第一句即点明项目本质FluentValidation is a .NET library for building strongly-typed validation rules.区别于「把规则写在字符串配置文件里」的传统方案FluentValidation 用 C# 表达式树Lambda直接引用被校验对象的属性编译器在编写阶段就能检查属性名拼写错误重构时也能同步感知属性改名。版本与运行环境官方文档明确给出版本矩阵FluentValidation 12支持 .NET 8 及更新版本包括 .NET 10。仓库主项目 src/FluentValidation/FluentValidation.csproj 的TargetFrameworknet8.0/TargetFramework也印证了这一目标框架。FluentValidation 11如果需要在旧运行时上运行应使用 11.x它运行于 .NET Standard 2.0、.NET Core 3.1、.NET 5 及更新版本。此外文档特别提示从 11 迁移到 12 之前务必阅读 docs/upgrading-to-12.md 了解破坏性变更。安装两种官方推荐方式在开始编写验证器之前需要为项目添加 FluentValidation 程序集引用。官方文档 docs/installation.md 提供了两种等价方式方式一Visual Studio 的 NuGet 包管理器控制台Install-Package FluentValidation方式二.NET CLI 终端命令dotnet add package FluentValidation安装完成后在代码文件顶部通过using FluentValidation;引入命名空间即可开始使用。创建第一个验证器定义被校验的模型以一个典型的业务对象为例public class Customer { public int Id { get; set; } public string Surname { get; set; } public string Forename { get; set; } public decimal Discount { get; set; } public string Address { get; set; } public string Postcode { get; set; } public bool HasDiscount { get; set; } }继承 AbstractValidator为特定对象定义一组校验规则需要创建一个继承自AbstractValidatorT的类其中T是被校验对象的类型。这是整个框架的入口基类源码见 src/FluentValidation/AbstractValidator.cs其中public abstract partial class AbstractValidatorT : IValidatorT, IEnumerableIValidationRule定义了规则集合与执行引擎。using FluentValidation; public class CustomerValidator : AbstractValidatorCustomer { }在构造函数中用 RuleFor 声明规则校验规则应当定义在验证器类的构造函数中。要针对某个属性指定规则调用RuleFor方法并传入一个标识目标属性的 Lambda 表达式。例如确保Surname不为 nullusing FluentValidation; public class CustomerValidator : AbstractValidatorCustomer { public CustomerValidator() { RuleFor(customer customer.Surname).NotNull(); } }官方首页index.rst给出的完整示例展示了多种内置校验器的组合用法public class CustomerValidator : AbstractValidatorCustomer { public CustomerValidator() { RuleFor(x x.Surname).NotEmpty(); RuleFor(x x.Forename).NotEmpty().WithMessage(Please specify a first name); RuleFor(x x.Discount).NotEqual(0).When(x x.HasDiscount); RuleFor(x x.Address).Length(20, 250); RuleFor(x x.Postcode).Must(BeAValidPostcode).WithMessage(Please specify a valid postcode); } private bool BeAValidPostcode(string postcode) { // custom postcode validating logic goes here } }这个示例一次性覆盖了入门阶段的四个高频能力NotEmpty()不允许空值/空字符串/空白/集合为空等见 src/FluentValidation/DefaultValidatorExtensions.cs 中NotEmpty的实现与注释null、空字符串、空白、空集合或类型默认值都会失败。WithMessage(...)自定义失败消息仅作用于紧随其前的规则实现见 src/FluentValidation/DefaultValidatorOptions.cs 中的WithMessage。When(...)条件规则仅当条件成立时执行校验。Must(...)自定义谓词校验把「业务规则」作为参数传入。从源码结构看RuleFor返回的IRuleBuilder上挂载了大量扩展方法NotNull、NotEmpty、Equal、Length、Must等它们内部统一通过SetValidator(...)把一个具体的PropertyValidator组件追加到规则链上——例如 src/FluentValidation/DefaultValidatorExtensions.cs 中NotNull的实现就是ruleBuilder.SetValidator(new NotNullValidatorT,TProperty())。这种「一条规则 多个验证组件」的管线设计正是链式校验能无缝拼接的底层原因。运行校验并读取结果Validate 方法实例化验证器对象调用Validate方法并传入待校验对象Customer customer new Customer(); CustomerValidator validator new CustomerValidator(); ValidationResult result validator.Validate(customer);在源码层面Validate(T instance)会构造一个ValidationContextT并进入校验引擎src/FluentValidation/AbstractValidator.cs L98-L99。同时框架也提供异步版本ValidateAsync支持传入CancellationToken。解读 ValidationResultValidate返回的 ValidationResult 对象包含两个核心属性IsValid布尔值表示校验是否全部通过。源码实现为IsValid Errors.Count 0ValidationResult.cs L35即「没有错误即有效」。ErrorsValidationFailure对象集合包含每条失败详情。每个 ValidationFailure 至少提供PropertyName失败对应的属性名ErrorMessage失败消息AttemptedValue导致失败时该属性的值此外还有Severity严重级别、ErrorCode错误码、CustomState自定义状态等高级字段用于后续精细化处理。把失败信息输出到控制台using FluentValidation.Results; Customer customer new Customer(); CustomerValidator validator new CustomerValidator(); ValidationResult results validator.Validate(customer); if (!results.IsValid) { foreach (var failure in results.Errors) { Console.WriteLine(Property failure.PropertyName failed validation. Error was: failure.ErrorMessage); } }一键合并所有错误消息可以调用ValidationResult的ToString()把所有错误消息合并为单个字符串。默认使用换行符分隔也可以传入自定义分隔符ValidationResult results validator.Validate(customer); string allMessages results.ToString(~); // 每条消息以 ~ 分隔底层实现见 ValidationResult.cs L92-L103ToString()委托给ToString(Environment.NewLine)而ToString(string separator)用string.Join把每条ErrorMessage拼接起来。注意若无校验错误ToString()返回空字符串。如果想把结果按属性分组交给上层 API如 Web API 返回结构化错误ValidationResult还提供了ToDictionary()方法返回「属性名 → 错误消息数组」的字典同文件 L111-L118这在对接 ASP.NET Core 模型状态时非常实用。链式校验一条 RuleFor 多个规则可以为同一属性串联多个校验器它们会依次执行using FluentValidation; public class CustomerValidator : AbstractValidatorCustomer { public CustomerValidator() { RuleFor(customer customer.Surname).NotNull().NotEqual(foo); } }上述代码确保Surname不为 null且不等于字符串foo。串联的每个校验器都是独立组件默认情况下全部执行除非配置了级联模式见下文失败信息会同时进入Errors集合。这也是 src/FluentValidation/Internal/RuleComponent.cs 等内部组件把规则建模为「组件列表」的原因。抛出异常ValidateAndThrow 与选项 API快速失败并抛异常大多数场景希望「校验失败即抛异常」可以使用ValidateAndThrow扩展方法Customer customer new Customer(); CustomerValidator validator new CustomerValidator(); validator.ValidateAndThrow(customer);该方法抛出 ValidationException异常对象的Errors属性中包含全部失败详情public IEnumerableValidationFailure Errors。注意ValidateAndThrow是扩展方法必须在文件顶部using FluentValidation;才能使用。异步场景对应ValidateAndThrowAsync支持 CancellationToken。它本质上是选项 API 的快捷方式从源码看src/FluentValidation/DefaultValidatorExtensions_Validate.cs L58-L62ValidateAndThrow的实现是validator.Validate(instance, options { options.ThrowOnFailures(); });即等价于validator.Validate(customer, options options.ThrowOnFailures());在框架内部ThrowOnFailures标志存放在校验上下文中src/FluentValidation/IValidationContext.cs 中bool ThrowOnFailures默认 false校验结束后 AbstractValidator.cs L175-L177 会检查if (!result.IsValid context.ThrowOnFailures)并调用RaiseValidationException抛出异常。组合更多选项如果需要在抛异常的同时组合「规则集」或「指定属性」校验可以在选项回调里同时配置多项validator.Validate(customer, options { options.ThrowOnFailures(); options.IncludeRuleSets(MyRuleSets); options.IncludeProperties(x x.Name); });其中IncludeRuleSets对应规则集Rule Set功能详见 docs/rulesets.mdIncludeProperties用于只校验指定属性详见 docs/specific-properties.md。若需自定义抛出的异常类型可参考 docs/advanced.md 中的「Customizing the Validation Exception」小节。复杂属性验证器的复用与内联子规则用 SetValidator 复用子验证器验证器可以复用于复杂属性。例如有两个类Customer与Addresspublic class Customer { public string Name { get; set; } public Address Address { get; set; } } public class Address { public string Line1 { get; set; } public string Line2 { get; set; } public string Town { get; set; } public string Country { get; set; } public string Postcode { get; set; } }先定义AddressValidatorpublic class AddressValidator : AbstractValidatorAddress { public AddressValidator() { RuleFor(address address.Postcode).NotNull(); //etc } }然后在CustomerValidator中通过SetValidator复用public class CustomerValidator : AbstractValidatorCustomer { public CustomerValidator() { RuleFor(customer customer.Name).NotNull(); RuleFor(customer customer.Address).SetValidator(new AddressValidator()); } }此时调用CustomerValidator.Validate(...)会同时执行CustomerValidator与AddressValidator中的规则并把结果合并到同一个ValidationResult中。仓库测试 src/FluentValidation.Tests/ChainedValidationTester.cs 与 src/FluentValidation.Tests/AbstractValidatorTester.cs 中均有SetValidator组合父子验证器的用例。关键行为如果子属性为 null子验证器不会执行这是有意的空安全设计避免 NullReferenceException。内联子规则除了复用子验证器也可以直接内联定义子属性规则RuleFor(customer customer.Address.Postcode).NotNull()注意此写法不会对Address自动执行 null 检查因此应显式添加条件RuleFor(customer customer.Address.Postcode).NotNull().When(customer customer.Address ! null)两种写法的取舍SetValidator适合跨对象复用的规则如 Address 被多个实体引用内联写法适合仅此一处需要的简单规则。进阶全局配置与级联模式虽然入门阶段可以零配置开箱即用但理解全局配置有助于写出行为符合预期的验证器。核心配置类 ValidatorOptions.Global 是ValidatorConfiguration类型的静态实例关键默认值包括DefaultClassLevelCascadeMode与DefaultRuleLevelCascadeMode默认均为CascadeMode.ContinueValidatorOptions.cs L46、L54即所有规则/校验器无论失败与否都会继续执行。Severity默认Severity.Error。PropertyChainSeparator默认.用于嵌套属性失败时的属性名拼接。LanguageManager默认LanguageManager实例负责内置错误消息的本地化见 src/FluentValidation/Resources/LanguageManager.cs 与 docs/localization.md。级联模式可以分别作用于类级别与规则级别AbstractValidatorT上的ClassLevelCascadeMode/RuleLevelCascadeMode属性或CascadeMode扩展方法见 src/FluentValidation/DefaultValidatorOptions.cs L92-L111Continue所有校验器都执行无论前面是否失败Stop同一条规则链中第一个校验器失败后即停止该链的后续校验。例如把RuleLevelCascadeMode设为Stop后RuleFor(x x.Surname).NotNull().NotEqual(foo)中若NotNull失败NotEqual将不再执行。相关行为细节可查阅 docs/cascade.md。文档地图官方文档的完整导航docs/index.rst用 Sphinx toctree 组织起整套官方文档以下按章节给出仓库内的对应文档便于按需深入Getting Started入门docs/installation.md安装docs/start.md创建第一个验证器本文主体docs/collections.md集合校验RuleForEach、{CollectionIndex}占位符Configuring Validators配置验证器docs/configuring.md验证器配置docs/conditions.md条件规则When/UnlessBuilding Rules构建规则docs/built-in-validators.md内置校验器清单docs/custom-validators.md自定义校验器Other Features其他特性docs/including-rules.md包含/复用规则docs/specific-properties.md校验指定属性docs/rulesets.md规则集docs/cascade.md级联模式docs/di.md依赖注入集成对应 src/FluentValidation.DependencyInjectionExtensions 项目docs/async.md异步校验docs/severity.md严重级别docs/error-codes.md错误码docs/custom-state.md自定义状态Localization本地化docs/localization.md内置 50 种语言的错误消息本地化仓库 src/FluentValidation/Resources/Languages 目录下可见中文简体、繁体、日文、德文等语言文件Testing测试docs/testing.md使用扩展方法编写校验测试仓库 src/FluentValidation.Tests 提供了大量测试样例与 src/FluentValidation/TestHelper 测试辅助类Advanced高级docs/dependentrules.md依赖规则docs/inheritance.md验证器继承docs/advanced.md高级主题ASP.NET Integration框架集成docs/aspnet.mdASP.NET Core 集成docs/blazor.mdBlazor 集成Upgrading升级指南docs/upgrading-to-12.md、docs/upgrading-to-11.md、docs/upgrading-to-10.md、docs/upgrading-to-9.md、docs/upgrading-to-8.md小结入门后的三条路径至此你已经掌握了 FluentValidation 的核心闭环继承AbstractValidatorT→ 构造函数中用RuleFor/SetValidator声明规则 →Validate/ValidateAndThrow执行校验 → 读取ValidationResult的IsValid/Errors处理结果。在此基础上可以按需深入三条路径规则扩展翻阅 docs/built-in-validators.md 掌握全部内置校验器或参考 src/FluentValidation/Validators 目录下的 30 个校验器实现框架集成对接 ASP.NET Core 自动校验与依赖注入docs/aspnet.md、docs/di.md工程化落地用 Rule Set、级联模式、严重级别与错误码统一团队的错误输出规范并用 docs/testing.md 的测试辅助编写回归用例。这些进阶能力的源码、测试与文档在本仓库中均可直接查阅例如内置校验器定义于 src/FluentValidation/Validators对应的测试用例位于 src/FluentValidation.Tests 下的同名*ValidatorTests文件是理解每个校验器精确行为含边界值的可靠参考。赞分享后端【免费下载链接】FluentValidationA popular .NET validation library for building strongly-typed validation rules.项目地址https://gitcode.com/gh_mirrors/fl/FluentValidation点击查看免费下载相关推荐FluentValidation 入门实战用 AbstractValidator 与 RuleFor 构建强类型验证规则FluentValidation 入门实战用 AbstractValidator 与 RuleFor 构建强类型验证规则 FluentValidation 是后端FluentValidation强大的.NET强类型验证库入门指南FluentValidation强大的.NET强类型验证库入门指南 FluentValidation是一个专为.NET平台设计的强大验证库通过流畅接口和La后端Pydantic 入门指南基于 Python 类型注解的数据校验实战Pydantic 入门指南基于 Python 类型注解的数据校验实战 Pydantic 是目前 Python 生态中使用最广泛的数据校验Data Valid后端序列化上一篇终极视频下载指南如何用VideoDownloadHelper轻松保存任何在线视频资源下一篇彻底掌控Windows窗口尺寸WindowResizer开源工具深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考