后端【免费下载链接】FluentValidationA popular .NET validation library for building strongly-typed validation rules.项目地址https://gitcode.com/gh_mirrors/fl/FluentValidation点击查看免费下载FluentValidation 是 .NET 生态中用于构建强类型验证规则的流行库它可以被无缝接入 ASP.NET Core 应用程序对进入系统的模型进行校验。本篇技术指南以 docs/aspnet.md 为骨架结合本仓库的 DI 扩展与核心源码系统讲解在 ASP.NET CoreMVC / Razor Pages / Minimal APIs中使用 FluentValidation 的三种主流方式手动验证、基于 ASP.NET 验证管道的自动验证、基于 Action Filter 的自动验证并深入剖析验证器注册原理、ModelState 集成、客户端验证元数据以及ToDictionary等关键 API。读完本文你将能根据项目形态传统 MVC 还是 Minimal API正确选型并落地一套可维护、可调试的验证方案。三种验证方式概览在 ASP.NET Core 应用中FluentValidation 验证传入模型主要有三条路径各有权衡方式触发时机优点局限手动验证Manual validation在控制器/API 端点内部显式调用最直观逻辑完全可见易于调试与测试需要在每个入口重复调用自动验证ASP.NET 验证管道模型绑定阶段、控制器 Action 执行之前无缝接入减少样板代码非异步异步规则会抛异常、仅支持 MVC/Razor Pages、难以调试官方已不推荐新项目使用自动验证Action Filter通过过滤器在端点执行前拦截支持异步弥补管道方案的同步缺陷官方不内置需借助第三方包手动验证时验证器被注入到控制器或 API 端点中由开发者显式调用并处理结果——这是最直接、最容易看清执行过程的方案而自动验证则由 ASP.NET 在管道更早的阶段自动调用 FluentValidation使模型在进入控制器 Action 之前就已校验完毕。起步定义一个验证器后续所有示例都围绕一个Person对象及其验证器PersonValidator展开定义如下public class Person { public int Id { get; set; } public string Name { get; set; } public string Email { get; set; } public int Age { get; set; } } public class PersonValidator : AbstractValidatorPerson { public PersonValidator() { RuleFor(x x.Id).NotNull(); RuleFor(x x.Name).Length(0, 10); RuleFor(x x.Email).EmailAddress(); RuleFor(x x.Age).InclusiveBetween(18, 60); } }验证规则定义在验证器构造器中通过RuleFor传入属性选择表达式来声明式地组合规则。关于如何创建第一个验证器、链式调用多个验证器、使用SetValidator组合子验证器等基础概念可参考 docs/start.md。如果你在使用 MVC、Web API 或 Razor Pages需要把验证器注册到Startup.ConfigureServices中的 Service ProviderMinimal APIs 的注册方式见下文专节public void ConfigureServices(IServiceCollection services) { // 如果使用 MVC 或 WebApi通常已有 AddMvc() 或 AddControllers() 调用 services.AddMvc(); // ... 其他配置 ... services.AddScopedIValidatorPerson, PersonValidator(); }这里通过AddScoped将PersonValidator注册到服务容器中。注意每个验证器必须注册为IValidatorT其中T是被验证的类型。即PersonValidator继承自AbstractValidatorPerson就应注册为IValidatorPerson。IValidatorT接口正是 FluentValidation 的核心契约定义见 src/FluentValidation/IValidator.cs它提供同步的Validate(T instance)、异步的ValidateAsync(T instance, CancellationToken)以及CreateDescriptor()等成员AbstractValidatorT则实现了该接口并托管规则集合与执行逻辑见 src/FluentValidation/AbstractValidator.cs。自动注册扫描程序集中的全部验证器手动逐个AddScoped在验证器数量庞大时非常繁琐。此时可引入FluentValidation.DependencyInjectionExtensions包本仓库中对应工程为 src/FluentValidation.DependencyInjectionExtensions入口见 ServiceCollectionExtensions.cs借助其扩展方法一次性注册指定程序集中的所有验证器public void ConfigureServices(IServiceCollection services) { services.AddMvc(); // ... 其他配置 ... services.AddValidatorsFromAssemblyContainingPersonValidator(); }AddValidatorsFromAssemblyContainingPersonValidator()会以PersonValidator所在程序集为扫描范围自动将所有验证器注册进服务容器。更完整的 DI 集成说明包括生命周期参数、过滤、单例注意事项等可参考 docs/di.md。源码级原理扫描与注册是如何发生的从源码看自动注册分为“扫描”与“注册”两步扫描AssemblyScanner.FindValidatorsInAssembly通过assembly.GetExportedTypes()获取程序集中所有公开导出的类型若传入includeInternalTypes: true则改用GetTypes()连内部类型一并纳入然后筛选出所有非抽象、非泛型类型定义且实现了IValidator泛型接口的类型产出AssemblyScanResult含InterfaceType与ValidatorType实现见 src/FluentValidation/AssemblyScanner.cs。注册AddScanResult为每个扫描结果注册两条服务描述——先用TryAddEnumerable将实现类注册到其IValidatorT接口支持解析IEnumerableIValidatorT再用TryAdd注册为自身类型。TryAdd语义保证重复调用扫描方法不会产生重复注册见 ServiceCollectionExtensions.cs。这一行为在测试中得到了验证src/FluentValidation.Tests/DependencyInjectionExtensions/ServiceCollectionExtensionsTests.cs 中的Should_register_validator_service_types_only_once与Should_register_validators_as_enumerable_interface_type_only_once断言了重复调用AddValidatorsFromAssemblyContaining时服务仅注册一次、且同一IValidatorT接口可解析出多个实现。生命周期与过滤选项AddValidatorsFromAssemblyContainingT的完整签名如下默认注册为Scoped即 Web 应用中按请求作用域解析public static IServiceCollection AddValidatorsFromAssemblyContainingT( this IServiceCollection services, ServiceLifetime lifetime ServiceLifetime.Scoped, FuncAssemblyScanner.AssemblyScanResult, bool filter null, bool includeInternalTypes false)lifetime可显式指定Singleton或Transient。若注册为 Singleton必须确保不注入任何 Transient 或请求作用域的依赖否则会产生“单例持有非单例依赖”的经典 DI 陷阱官方建议把验证器注册为 Transient 是最简单安全的选择。filter提供过滤函数以排除部分验证器例如跳过CustomerValidatorservices.AddValidatorsFromAssemblyContainingMyValidator(ServiceLifetime.Scoped, filter filter.ValidatorType ! typeof(CustomerValidator));includeInternalTypes默认false即只扫描 public 类型。此外还有多种重载AddValidatorsFromAssemblyContaining(typeof(UserValidator))以类型实例扫描、AddValidatorsFromAssembly(Assembly.Load(SomeAssembly))直接按程序集引用扫描、AddValidatorsFromAssemblies(IEnumerableAssembly)一次扫描多个程序集见 ServiceCollectionExtensions.cs。手动验证把结果写入 ModelState手动验证的核心思路是把验证器注入控制器或 Razor Page在 Action 中显式调用并处理结果。以创建Person的控制器为例public class PeopleController : Controller { private IValidatorPerson _validator; private IPersonRepository _repository; public PeopleController(IValidatorPerson validator, IPersonRepository repository) { // 注入验证器同时注入用于持久化的 DB 上下文 _validator validator; _repository repository; } public ActionResult Create() { return View(); } [HttpPost] public async TaskIActionResult Create(Person person) { ValidationResult result await _validator.ValidateAsync(person); if (!result.IsValid) { // 将验证结果复制进 ModelState。 // ASP.NET 使用 ModelState 集合向视图填充错误信息。 result.AddToModelState(this.ModelState); // 验证失败时重新渲染视图 return View(Create, person); } _repository.Save(person); // 保存 person 到数据库或执行其他逻辑 TempData[notice] Person successfully created; return RedirectToAction(Index); } }因为验证器已注册到 Service Provider它会通过构造函数注入到控制器中随后在CreateAction 里用ValidateAsync触发校验。验证失败时需要把错误信息回传给视图。Flutter 的ValidationResult本身不直接感知 ASP.NET 的ModelState因此文档给出了一个扩展方法把错误集合复制进ModelStateDictionarypublic static class Extensions { public static void AddToModelState(this ValidationResult result, ModelStateDictionary modelState) { foreach (var error in result.Errors) { modelState.AddModelError(error.PropertyName, error.ErrorMessage); } } }ValidationResult的结构见 src/FluentValidation/Results/ValidationResult.csIsValid等价于Errors.Count 0Errors是ValidationFailure的集合其中PropertyName、ErrorMessage、AttemptedValue、Severity等字段定义见 src/FluentValidation/Results/ValidationFailure.cs。该扩展方法正是逐条取出PropertyName/ErrorMessage写入 ModelState 的。对应的 Razor 视图会从ModelState中拾取错误消息并渲染到对应属性旁model Person div asp-validation-summaryModelOnly/div form asp-actionCreate Id: input asp-forId / span asp-validation-forId/span br / Name: input asp-forName / span asp-validation-forName/span br / Email: input asp-forEmail / span asp-validation-forEmail/span br / Age: input asp-forAge / span asp-validation-forAge/span br /br / input typesubmit valuesubmit / /form提示如果你写的是 API 控制器返回 JSON 而非渲染视图失败时应返回ValidationProblemDetails或BadRequest而不是视图结果。Minimal API 场景下则使用Results.ValidationProblem(...)详见下文。自动验证两种实现路径自动验证会在控制器 Action 执行之前实例化并调用验证器即当你的 Action 被调用时 ModelState 中已经填充好验证结果。官方文档给出了两条实现路径使用 ASP.NET 的验证管道不再推荐使用 Action Filter由第三方包支持路径一ASP.NET 验证管道不再推荐FluentValidation.AspNetCore包通过接入 ASP.NET Core MVC 内建的验证过程模型绑定阶段实现自动验证。这种方式更“无缝”但存在几个明显缺点管道不支持异步如果验证器包含异步规则运行时将抛出异常——自动验证无法执行异步验证器。仅限 MVC只对 MVC Controllers 和 Razor Pages 生效不适用于 Minimal APIs 或 Blazor 等更新的 ASP.NET 部件。难以调试自动验证的“魔法”特性使问题排查变得困难大量逻辑在幕后自动完成。警告官方已不再建议新项目使用此方案但它仍可供遗留项目使用。FluentValidation.AspNetCore包的安装与使用说明在其独立项目页面该包当前已停止维护仅保持可用状态。路径二Action Filter另一种自动验证方案是使用 Action Filter。由于过滤器支持异步执行它规避了上述验证管道“不能跑异步规则”的同步限制。此方案官方不内置支持可使用第三方包如SharpGrip.FluentValidation.AutoValidation实现——用法为在端点或全局配置中启用过滤器由过滤器在 Action 执行前自动对模型参数执行验证并填充 ModelState具体接入方式以该包文档为准。客户端验证元数据与 AJAX 两种思路FluentValidation 本质上是服务端校验库本身不提供任何客户端验证逻辑。但它能够像 ASP.NET 默认验证特性那样为生成 HTML 元素提供可用于客户端框架如 jQuery Validate的验证元数据。要使用该元数据需要安装独立的FluentValidation.AspNetCore包注意该包已不再支持但仍可使用。另一种思路是放弃客户端验证改用 AJAX 把完整服务端规则跑一遍例如借助FormHelper这类库。这样既保留 FluentValidation 的全部能力又维持了响应式交互体验。Minimal APIs 中的验证在 Minimal APIs 中使用 FluentValidation 时同样可以把验证器注册进服务容器若无依赖也可以直接实例化然后在 API 端点内显式调用var builder WebApplication.CreateBuilder(args); var app builder.Build(); // 注册验证器到服务容器或用上文任一自动注册方法 builder.Services.AddScopedIValidatorPerson, PersonValidator(); // 为演示注册一个 DB 访问仓储 // 请替换为你的应用中实际使用的仓储实现 builder.Services.AddScopedIPersonRepository, PersonRepository(); app.MapPost(/person, async (IValidatorPerson validator, IPersonRepository repository, Person person) { ValidationResult validationResult await validator.ValidateAsync(person); if (!validationResult.IsValid) { return Results.ValidationProblem(validationResult.ToDictionary()); } repository.Save(person); return Results.Created($/{person.Id}, person); });端点通过参数注入拿到IValidatorPerson调用ValidateAsync校验失败时用Results.ValidationProblem返回符合 RFC 7807 标准的ProblemDetails响应。关键 APIToDictionary上面用到的ValidationResult.ToDictionary()方法会按属性名分组错误消息输出IDictionarystring, string[]键为属性名、值为该属性关联的错误消息数组这正是ValidationProblem所期望的数据形状。该方法的源码实现位于 ValidationResult.cs以GroupBy(x x.PropertyName)聚合Errors而成。版本注意ToDictionary自FluentValidation 11.1起才内置在ValidationResult上。若使用更早版本需要自行实现等价扩展方法public static class FluentValidationExtensions { public static IDictionarystring, string[] ToDictionary(this ValidationResult validationResult) { return validationResult.Errors .GroupBy(x x.PropertyName) .ToDictionary( g g.Key, g g.Select(x x.ErrorMessage).ToArray() ); } }除手动调用外也可借助第三方包如SharpGrip.FluentValidation.AutoValidation、ForEvolve.FluentValidation.AspNetCore.Http为某个端点或一组端点挂上验证过滤器实现 Minimal API 场景下的自动验证避免在每个端点重复样板代码。补充同步校验与异常抛出的便捷入口虽然本文聚焦 ASP.NET Core 集成但了解IValidatorT的便捷入口有助于在端点内灵活处理端点内如果不需要异步可调用validator.Validate(person)同步重载定义于 AbstractValidator.cs。若希望校验失败时直接抛异常可调用扩展方法ValidateAndThrow/ValidateAndThrowAsync其实现等价于Validate(instance, options options.ThrowOnFailures())见 DefaultValidatorExtensions_Validate.cs。这一模式在 MVC 集成中很少使用通常要渲染错误给用户但在命令/服务层边界、批处理或需要“校验失败即中断”的场景中非常实用。小结与选型建议综合以上内容在 ASP.NET Core 中落地 FluentValidation 验证的推荐路径可归纳为注册用AddValidatorsFromAssemblyContainingT()批量注册默认Scoped复杂场景再按需调整生命周期与过滤规则保持验证器无状态、依赖简单避免 Singleton 陷阱。MVC / Razor Pages优先手动注入IValidatorT并在 Action 中调用ValidateAsync用AddToModelState扩展把错误同步进 ModelState 并回显到视图旧项目可继续使用基于验证管道的自动验证但需明确其不支持异步规则的约束。API / Minimal APIs手动调用验证器失败时以Results.ValidationProblem(validationResult.ToDictionary())返回标准问题详情注意ToDictionary需要 FluentValidation 11.1需要免样板时可选用第三方 Action Filter 包。客户端验证优先走 AJAX 复用服务端规则或按需使用不再维护的FluentValidation.AspNetCore元数据特性。如需进一步深入可继续阅读仓库中的 docs/aspnet.md本文骨架来源、docs/di.mdDI 与自动注册全解与 docs/start.md验证器基础语法。赞分享后端【免费下载链接】FluentValidationA popular .NET validation library for building strongly-typed validation rules.项目地址https://gitcode.com/gh_mirrors/fl/FluentValidation点击查看免费下载相关推荐FluentValidation在ASP.NET Core中的集成实践手动验证、自动验证与过滤器全解析FluentValidation在ASP.NET Core中的集成实践手动验证、自动验证与过滤器全解析 FluentValidation 是 .NET 生态中后端ASP.NET Boilerplate 数据验证指南DTO 自动校验、自定义验证与 FluentValidation 集成ASP.NET Boilerplate 数据验证指南DTO 自动校验、自定义验证与 FluentValidation 集成 导读 在 ASP.NET Boil后端Web框架依赖注入认证鉴权终极指南FluentValidation与ASP.NET Core自动模型验证的完整教程终极指南FluentValidation与ASP.NET Core自动模型验证的完整教程 FluentValidation是一个功能强大的.NET库它提供了后端上一篇终极AI学习助手DeepTutor如何解决你的学习难题下一篇Open-Shell为现代Windows注入经典灵魂的界面革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考