端点参数校验(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> |
想深入
- 保存路径的值域执法(同一标注第二面):EF 保存路径字段校验
- 端点管线槽位:Endpoints 使用说明
- API 参考:docs.kernlab.dev/loom/api