保存路径字段校验
数据质量值域执法——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 对齐列宽 |