SuperAPI AI 工具集

dotnet-validation-patterns

编程与开发

查看项目

更新于 10-16 10:05

技能介绍

用途

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。技能的收费、价格及平台信息暂未提供。