Table of Contents

保存路径字段校验

数据质量值域执法——EF Core 保存路径无校验(官方决策)留下的真空,由提交门执法缝补位。 上位:总览。

定位锚

校验做的是数据内容的规范合法性——数据质量。不是业务层的 API 校验。

判据(字段值域规定 vs 业务流程判断):这条规则是建库时规定的字段值域,还是运行时的业务流程判断?

  • 字段值域规定(长度/字符集/格式正则/数值最小最大/时间范围/必填——DB CHECK 约束级别的全部客观约束)= 数据质量 → 本件执法域;
  • 业务流程判断(余额够不够/库存有没有/状态能不能流转/跨表一致性)→ API 层/领域层,永不进本件。

价值锚:数据库文档设计的值域 = 校验声明——设计与存储的一致性由执法保证,杜绝"文档写 0-100、库里大量 >100/<0"的漂移;数据治理不再做"文档与库不符"的发现工程(VAL 保证脏数据不增长;存量清洗 = 数据治理工程,另一域)。

从零跑通

1. 实体属性上直接标 BCL DataAnnotations(零新词汇):

[EfEntity]
public sealed class User
{
    [StringLength(20), MinLength(2)]                 // 长度
    public string Name { get; set; } = "";

    [Range(0, 100_000)]                              // 数值范围
    public decimal Amount { get; set; }

    [RegularExpression(@"^[A-Z]{2}\d{6}$")]          // 格式
    public string DocNo { get; set; } = "";

    [EfCharSet(EfCharSets.Digits)]                   // 字符集(组合式 Flags)
    public string Remark { get; set; } = "";
}

2. 接线——AddLoomEf(...) 后缺省即开,无需配置:

services.AddLoomEf<AppDbContext>(o => o.UseSqlServer(cs));
// 关闭(零开销):loom.Validation.Enabled = false

3. 保存与承接——违规聚合后一次性抛:

try
{
    await db.SaveChangesAsync();
}
catch (LoomValidationException ex)
{
    foreach (var v in ex.Violations)   // EntityType / EntityKey / Member / Rule / ActualValue / Message
        logger.LogWarning("{Member} 违反 {Rule}:{Actual}", v.Member, v.Rule, v.ActualValue);
}

场景语义:Added = 全属性校验;Modified = 只校验本次变更属性(存量脏值不阻塞其他字段);读取不校验。

三道防线补中间道

道防线 谁执行 边界
API 层校验 业务/验证框架 体验最好但可绕过(内部服务/消息消费/后台任务/ETL 直调 DbContext 不经 API)
EF 保存校验(本件) 提交门执法缝(租户执法/只读档同位) 任何应用内路径统一生效——纵深防御中间道
DB CHECK 约束 数据库 最终防线(手写迁移)

声明面:BCL DataAnnotations 直接生效(零新词汇零第三方)+ Loom 组合式语法糖

public sealed class User
{
    [EfKey(EfKeyStrategy.Snowflake)]
    public long Id { get; set; }

    [StringLength(20), MinLength(2)]                 // BCL——执法器直接识别执行
    public string Name { get; set; } = "";

    [Range(0, 100_000)]
    public decimal Amount { get; set; }

    [RegularExpression(@"^[A-Z]{2}\d{6}$")]
    public string DocNo { get; set; } = "";

    [Range(typeof(DateTime), "2020-01-01", "2099-12-31")]   // 时间范围——BCL Type 重载(任意 IComparable)
    public DateTime OrderDate { get; set; }

    [EfCharSet(EfCharSets.Digits)]                        // 语法糖:纯数字
    [EfCharSet(EfCharSets.Letters | EfCharSets.Chinese)]  // 组合式:字母+中文
    public string Remark { get; set; } = "";
}
  • BCL 校验特性直接生效:Required / Range(含 Type 重载——任意 IComparable;字符串按 InvariantCulture 解析,规范 ISO 格式 yyyy-MM-dd)/ RegularExpression / StringLength / MinLength——一次标注双面生效(API 层验证框架同时认),不造平行校验词汇。值为 null 时 Range 视为合法(必填归 [Required]——执法域分工一致)。
  • 组合式语法糖 [EfCharSet]:Flags 枚举位组合,一个特性覆盖任意组合。
位 字符类 范围
Digits 数字 0-9
Lowercase 小写字母 a-z
Uppercase 大写字母 A-Z
Symbols 特殊符号 可见 ASCII 符号集(!@#$%^&* 等)
Chinese 中文 CJK 基本区
Letters(组合常量) 字母 = Lowercase | Uppercase

语义 = 白名单字符类(声明的位并集内逐字符放行,其余拒绝;空串放行——长度归 StringLength/列长度管)。派生 ValidationAttribute——API 层模型校验同样生效(双面)。

  • 列长度预检:HasMaxLength 映射联动——超长字符串保存前拒绝(治理文案:字段/上限/实际长度)——SQLite 原生无长度约束(超长静默截断 = 数据损坏面),EF 层预检补齐。

执法设计

  • 执法点:提交门 Capture 段(与租户执法/审计填值同管线同位)。
  • 场景分界(执法面精确到属性级):
场景 行为
Added 实体 全属性校验(新行必须全合规)
Modified 实体 只校验本次变更的属性——存量越界行被修改其他字段时不卡死(历史脏值不阻塞新写入)
读取/物化 不校验(读路径零开销;存量行照常物化)
存量脏数据 数据治理工程域(VAL 保证脏数据不增长,不做存量清洗)
  • 聚合异常:一次 SaveChanges 多字段违规 → 收集全部后一次性抛 LoomValidationException(违规清单:属性/规则/实际值/消息)——不是逐个试错。
  • 编译期物化:校验描述符进注册表,Regex 预编译缓存——提交门内联执法,开销与 SaveChanges 本身同量级;量化基线见 治理关键路径基线。
  • 开关:loom.Validation.Enabled(缺省 true——缺省安全;Off = 零开销跳过)。
  • 故障隔离(宪章):校验失败必须 Throw(保存路径执法);校验器自身异常按稳定性宪章隔离注入测试验收。

范围克制

字段级值域校验为止——不做跨字段规则、不做 IValidatableObject 执行、不做业务流程判断;不做 Phone/Email 强语义特性(规则易变——API 层职责;自定义正则 = BCL [RegularExpression] 直接用);"至少各含一个"密码策略语义不做(字符集 = 白名单,非组合要求)。

反模式

症状 为什么错 正确形态
存量脏行改其他字段被校验卡死 Modified 只校验变更属性——被卡说明改的就是越界属性 先清洗该字段(数据治理域),或关闭该规则重新评估
想关掉某实体的校验 开关是上下文级(缺省开) 修正声明;确需豁免 = Off 整档并理解失去中间道
用 [EfCharSet] 做"必须含数字和字母" 白名单语义——声明的位并集内放行,不是组合要求 组合要求归 API 层正则
校验当业务规则用(状态流转) 值域执法不管业务流程判断 领域层/API 层
SQLite 超长字符串静默入库 SQLite 无长度约束——但 EF 层有预检 预检被拒是正确行为;补 StringLength 对齐列宽

想深入