Table of Contents

端点参数校验(Validation)

定位

KernLab.Loom.Validation——端点参数校验 T1 源生成(三段式裁定:T1 语法 / T2 语义 / T3 事务不变式):契约属性 DataAnnotations 子集标注([Required]/[StringLength]/[MaxLength]/[MinLength]/[Range]/[RegularExpression]/[EmailAddress]/[Phone]/[Url])+ Loom 声明词汇(交叉字段比较 [LessThan]/[LessThanOrEqual]/[GreaterThan]/[GreaterThanOrEqual]、条件必填 [RequiredIf]/[RequiredIfNot])→ 物化直访属性静态校验函数(LoomValidation.Validate(契约[, culture]),零反射、AOT 安全、无错零分配);IValidatable<T> 纯函数逃生口并入;嵌套契约(任一 IEnumerable<T> 形态:数组/List/IReadOnlyCollection/ISet/HashSet/ImmutableArray…)递归生成;ErrorMessageResourceType/Name 经公共静态 ResourceManager.GetString(name, culture) 直访本地化(消息支持 {0}/{1} 占位);T2 IEndpointValidator<T> 接线归 Endpoints 面(管线固定槽位:绑定 → T1 → T2 → handler)。解决:API 层校验的反射开销与 AOT 不兼容——标准标注一次声明,编译期物化执行体。

快速上手

using System.ComponentModel.DataAnnotations;
using KernLab.Loom.Validation;

public sealed record CreateOrder
{
    [Required, StringLength(32)]
    public string Sku { get; init; } = "";

    [Range(1, 999)]
    public int Qty { get; init; }

    [RegularExpression(@"^[A-Z]{2}-\d{4}$")]
    public string BatchNo { get; init; } = "";

    [EmailAddress]
    public string? ContactEmail { get; init; }

    public DateTime StartAt { get; init; }

    [GreaterThanOrEqual(nameof(StartAt), ErrorMessage = "{0} 不得早于 {1}")]
    public DateTime EndAt { get; init; }

    public bool Urgent { get; init; }

    [RequiredIf(nameof(Urgent))]
    public string? UrgentReason { get; init; }

    public List<AddressInfo> Addresses { get; init; } = new();   // 嵌套契约——List<T>/ISet<T>/数组等全形态递归

    public AddressInfo Address { get; init; } = ...;      // 嵌套契约——递归生成(集合元素同)
}

// 物化校验(零反射直访;无错零分配)
var errors = LoomValidation.Validate(contract);                 // culture 缺省 = CurrentUICulture
var localized = LoomValidation.Validate(contract, CultureInfo.GetCultureInfo("zh-CN"));
if (errors.Length > 0)
{
    var problemErrors = LoomValidation.ToProblemErrors(errors);   // 字段路径 → 消息集(RFC 9457 errors 面)
    // → ValidationProblem(errors)
}

端点管线形态(T1 固定槽位)由 Endpoints 面装配——见 Endpoints 使用说明。

概念与术语

  • 三段式:T1 声明式校验(单字段值域 + 交叉字段比较 + 条件必填——本组件编译期物化执法);T2 语义校验(声明词汇表达不了的跨字段依赖/外部状态——IEndpointValidator<T>,Endpoints 管线槽位);T3 事务不变式(保存时一致性——数据库/工作单元域,不在此)。
  • ValidationError:字段路径(嵌套点路径形态)+ 消息——ToProblemErrors 汇聚为 ProblemDetails errors 字典。
  • IValidatable:纯函数逃生口——Validate() 契约自校验并入生成序列(复杂规则的后门,仍零反射)。

怎么选

方案 优势 代价 适用场景
Validation 生成器 标准标注 + Loom 声明词汇;零反射 AOT 安全;无错零分配 生成器进编译 API 端点参数校验(本组件)
手写 DataAnnotations Validator 零依赖 反射开销;AOT 不友好 非 AOT 的低频路径
FluentValidation 类 表达力强 第三方依赖;反射/表达式编译;AOT 配置面 规则极复杂的非 AOT 服务

决策:AOT 面/高频端点选本组件;能用声明词汇表达的交叉/条件规则留在 T1(编译期物化),超出词汇的复杂语义走 T2(IEndpointValidator<T>);事务不变式归存储层。

怎么用

单字段值域(T1)

BCL 九件直接标:[Required] / [StringLength] / [MaxLength] / [MinLength] / [Range] / [RegularExpression] / [EmailAddress] / [Phone] / [Url]——不造平行校验词汇。 其中前五类与 EF 保存路径校验同一识别面(一次标注双面生效:端点 T1 + EF 保存执法,见 EF 保存路径字段校验); [EmailAddress]/[Phone]/[Url]/[MaxLength] 目前仅 T1 识别。

绝静默:子集外的 ValidationAttribute(如 [Compare]/[CreditCard]/[CustomValidation])或 标注类型不匹配(如 [EmailAddress] 标在 int 上)→ KLSG145 Warning(该注解不参与校验); 请改用 IValidatable<T> 或扩展支持集。

交叉字段比较(声明式 T1)

public DateTime StartAt { get; init; }

[GreaterThanOrEqual(nameof(StartAt))]          // A >= B
public DateTime EndAt { get; init; }

[LessThan(nameof(EndAt))]                      // A < B
public DateTime? SoftEndAt { get; init; }
  • 四件:[LessThan] / [LessThanOrEqual] / [GreaterThan] / [GreaterThanOrEqual]——语义 = 标注属性 A 与目标 B 的关系(A < B 等)。
  • 目标解析:同一契约继承链内的可读实例字段/属性(含基类成员);自引用、目标缺失、目标非字段/属性、 static/private/protected、两侧核心类型不一致或不在支持集 → KLSG155 / KLSG156 Error(编译期拒绝,绝不静默丢校验)。
  • 支持类型(两侧核心类型一致,可空性可不同):数值基元(含 char)/ DateTime / DateTimeOffset / TimeSpan / DateOnly / TimeOnly(C# 关系运算符);string(String.CompareOrdinal 序数比较, 与 culture 无关);Guid(CompareTo)。自定义类型/枚举/bool 排序不在支持集。
  • null 语义:任一侧为 null → 比较跳过(通过)——存在性归 [Required]/[RequiredIf],避免同一缺失重复报错。

条件必填(声明式 T1)

public bool Urgent { get; init; }

[RequiredIf(nameof(Urgent))]                   // Urgent 置位时必填
public string? UrgentReason { get; init; }

[RequiredIfNot(nameof(Urgent))]                // Urgent 未置位时必填
public string? StandardNote { get; init; }

[RequiredIf(nameof(Urgent), AllowEmptyStrings = true)]
public string? Comment { get; init; }
  • 必填语义 = 既有 [Required]:null 不过;string 空串缺省不过(AllowEmptyStrings = true 放行空串)。
  • 标志形态白名单:bool(true = 置位)/ bool?(== true = 置位,null/false = 未置位)/ 任意可空值类型 T?(HasValue = 置位)。引用类型与非 bool 非可空值类型(string/int 等)语义歧义 → KLSG157 Error。
  • 标注属性为非可空值类型(恒存在)→ KLSG145 Warning(条件必填不生成规则)。
  • 标志目标与比较目标共用解析规则(继承链字段/属性;自引用/缺失/不可读 → KLSG157)。

消息占位参数

错误消息(ErrorMessage 字面量、缺省文案、ErrorMessageResource* 本地化字符串)统一支持:

占位 含义
{0} 标注字段名
{1} 目标名(交叉比较的被比较成员 / 条件必填的标志名)
[GreaterThanOrEqual(nameof(StartAt), ErrorMessage = "{0} 不得早于 {1}")]

替换仅在违规路径发生(合法路径零格式化开销);无占位原串直返;格式串非法(未配对花括号等)回退原串 不抛异常。格式化 culture = Validate(contract, culture) 的 culture ?? CurrentCulture。

本地化消息

ErrorMessageResourceType + ErrorMessageResourceName 生成 {ResourceType}.ResourceManager.GetString(name, culture) 直访(非反射,同 Display 底座)—— 资源类型须暴露公共静态 ResourceManager 属性(标准强类型 resx 生成类形态);缺该属性 → KLSG146 Warning 并回退 ErrorMessage 字面量/缺省文案。culture 来自 LoomValidation.Validate(contract, culture),缺省 null = CurrentUICulture(DataAnnotations 同义)。 本地化字符串中的 {0}/{1} 占位与字面量同路径替换(见上节)。

嵌套与集合

成员/元素类型是已标注契约 → 递归校验(点路径错误定位);集合覆盖任一 IEnumerable<T> 形态 (数组/List<T>/IReadOnlyList<T>/IReadOnlyCollection<T>/ISet<T>/HashSet<T>/ImmutableArray<T>…)—— 逐元素递归,路径保持 Lines[0].Sku;无索引器形态(ISet<T>)经 foreach 遍历,下标仍入路径。

自校验逃生口

契约实现 IValidatable<T>——Validate() 输出并入错误集(与标注规则同一次调用产出)。

T2 语义校验

声明词汇表达不了的跨字段依赖/外部状态校验实现 IEndpointValidator<T>(ValidateAsync(契约, ct))——Endpoints 面管线固定槽位接线,T1 通过后才执行。

反模式

症状 为什么错 正确形态
用 IValidatable<T> 手写已有声明词汇的交叉/条件规则 重复劳动且逃出物化直访的一致性 [LessThan] 族 / [RequiredIf] 族(声明式 T1)
把声明词汇表达不了的复杂跨字段语义硬塞进 T1 T1 只物化静态纯函数——外部状态/I/O 不在其位 复杂语义走 IEndpointValidator<T>(T2)
把事务不变式塞进校验器 T3 归存储/工作单元域——校验器看不到提交时点 提交门执法(EF 保存校验)或 UoW 约束
期望 EF 实体上自动跑同一套 T1 T1 是端点管线槽位,不是保存路径 保存路径值域执法 = EF 保存校验(Runtime VAL)——同一标注双面生效
errors 逐个 try-catch 收集 物化函数一次收集全量错误 Validate 返回错误集 + ToProblemErrors 一次汇聚

边界(诚实声明)

边界 说明
JsonElement / 非 CLR 契约 本组件只校验编译期已知 CLR 成员;动态 JSON 形状的 Schema 校验归消费方自建(如 TC.Traffic 的 SchemaValidator),不是本组件能力
自定义运算符重载 不探测用户自定义 operator <——只认内建可比较支持集;不支持即 KLSG156
反射式运行时 [LessThan]/[RequiredIf] 族是 Loom 自有声明词汇(非 ValidationAttribute 子类)——Validator.TryValidateObject 不会执行它们;T1 唯一权威 = 生成器
跨嵌套对象比较 目标只在声明契约继承链解析;跨父/子对象规则归 T2 或 IValidatable<T>

想深入

性能

量化基线:t1-validation-baseline.md。