用途
dotnet-validation-patterns 介绍 .NET 内置的校验模式,这些模式不需要引入第三方包。它用于指导在 .NET 应用中校验模型和 IOptions,帮助开发者在不同复杂度场景下选择合适的校验机制。技能明确指出:应优先使用这些内置机制作为默认方案,只有当复杂领域规则超出声明式特性的表达能力时,才保留 FluentValidation。
主要能力
技能覆盖以下范围:
- DataAnnotations 特性与 Validator.TryValidateObject
- 用于跨属性校验的 IValidatableObject
- 用于启动时选项校验的 IValidateOptions
- 自定义 ValidationAttribute 的编写
明确不在技能范围内的内容:
- API 管道集成(端点过滤器、ProblemDetails、AddValidation),参见 dotnet-input-validation
- Options 模式绑定与 ValidateOnStart 注册,参见 dotnet-csharp-configuration
- 校验在架构分层中的位置,参见 dotnet-architecture-patterns
校验方式决策
技能提供按复杂度选择校验方式的指引:
- DataAnnotations(默认):声明式的 [Required]、[Range]、[StringLength]、[RegularExpression] 等特性。最适合 DTO、请求模型和选项类上的简单属性级约束。
- IValidatableObject:实现 Validate() 处理同一对象内的跨属性规则。最适合日期范围比较、条件必填字段、跨多个属性的业务规则。
- 自定义 ValidationAttribute:继承 ValidationAttribute 实现可复用的属性级规则。最适合跨多个模型应用的领域特定约束(如 SKU 格式、邮编、货币代码)。
- IValidateOptions<T>:在启动时校验配置/选项类,可访问 DI 服务。最适合跨属性选项检查、依赖环境的校验、快速失败启动。
- FluentValidation:第三方库,用于复杂、可测试的流式 API 校验。最适合异步校验器、依赖数据库的规则、深度嵌套的对象图。
总体指引:从 DataAnnotations 开始;当出现跨属性规则时加入 IValidatableObject;只有当规则超出声明式特性能力时才引入 FluentValidation。
使用方式
DataAnnotations
System.ComponentModel.DataAnnotations 命名空间通过特性提供声明式校验。这些特性可与 MVC 模型绑定、Validator.TryValidateObject 以及 .NET 10 源生成校验管道配合工作。
技能列出了标准特性参考表,包括 [Required]、[StringLength]、[Range]、[RegularExpression]、[EmailAddress]、[Phone]、[Url]、[CreditCard]、[Compare]、[MaxLength]/[MinLength]、[AllowedValues](.NET 8+)、[DeniedValues](.NET 8+)、[Length](.NET 8+)、[Base64String](.NET 8+),并给出每个特性的用途与示例。
自定义 ValidationAttribute
可创建属性级自定义特性(应用于属性或参数),也可创建类级自定义特性(应用于整个类,处理多属性联动),例如 DateRangeAttribute 用于校验开始/结束日期范围。
IValidatableObject
实现 IValidatableObject 可在模型内部进行跨属性校验。该接口在所有单独的特性校验通过后运行(在使用 MVC 模型绑定或 Validator.TryValidateObject 且 validateAllProperties: true 时)。选择标准:当校验逻辑特定于单个模型且涉及多个属性时用 IValidatableObject;当同一规则适用于多个模型(可复用)时用自定义 ValidationAttribute。
IValidateOptions
使用 IValidateOptions<T> 在启动时对选项/配置类进行复杂校验。与 DataAnnotations 不同,该接口支持跨属性检查、DI 注入依赖和编程式逻辑,并可结合 ValidateOnStart() 实现快速失败。可同时使用 DataAnnotations 处理简单属性约束、IValidateOptions<T> 处理跨属性或环境相关逻辑。
手动校验
通过 Validator.TryValidateObject 可在 MVC/Minimal API 管道之外以编程方式运行 DataAnnotations 校验,适用于后台服务、控制台应用或领域逻辑。技能特别提醒:必须传入 validateAllProperties: true,否则只检查 [Required],会静默跳过 [Range]、[StringLength]、[RegularExpression] 等所有其他特性。
嵌套对象的递归校验
Validator.TryValidateObject 默认不会递归进入嵌套对象或集合,技能提供了递归校验的实现思路,并使用 visited 集合避免循环引用。
适用场景
适用于需要在 .NET 应用中对 DTO、请求模型、配置/选项类进行校验,且希望优先使用内置机制、避免引入第三方库的场景。包括后台服务中的手动校验、启动时配置快速失败等。
限制
技能的介绍在递归校验代码处截断,完整实现细节暂未提供。API 管道集成、Options 模式绑定与 ValidateOnStart 注册、校验的架构分层位置均不在本技能范围内,需参考其他技能。FluentValidation 的适用场景仅作决策提及,具体模式参见 dotnet-input-validation。技能的收费、价格及平台信息暂未提供。