查询与投影
过滤器族怎么自动生效、影子列怎么查、分页、投影映射、动态视图、受管批操作与逃逸舱。 动态条件的安全下推见查询规则引擎。
可运行 sample:
samples/Query/App([Filterable] 目录 + QueryDsl + ApplyFilter)。
查询:租户/软删/影子列/分页
// 全局过滤器自动生效(租户恒在 + 软删子条件),业务查询零感知
var open = await db.Orders.Where(o => o.Amount > 100).ToListAsync();
// 软删旁路(受管口;IgnoreQueryFilters 全量旁路走编译期 KLSG211 + 运行时 Throw 双闸)
using (db.IncludeDeletedScope())
{
var withDeleted = await db.Orders.CountAsync();
}
// 影子列查询(列名常量——真源是注册表)
var legacy = await db.Orders
.Where(o => EF.Property<string>(o, LoomColumns.Order.LegacyRef) == "R-1")
.ToListAsync();
// 分页
var page = await db.Orders.OrderByDescending(o => o.Id).ToPagedAsync(1, 20);
租户值每次执行经身份缝求值;IncludeDeletedScope() 置位/Dispose 退位,支持嵌套与并行上下文各自独立。租户条件永不旁路——见多租户与身份基座。
投影与映射([EfProject])
[EfProject(typeof(Order))] // 多源:再标一个 [EfProject(typeof(Customer))],成员先到先得
public sealed record OrderListItem
{
public long Sn { get; init; } // 同名同型直映射
[EfAlias("Amount")]
public decimal Total { get; init; } // 别名:Total ← Order.Amount
[EfIgnore]
public string? Note { get; init; } // 显式忽略
public CustomerSummary Customer { get; init; } // 嵌套:成员类型是注册投影即递归(同名单导航,深度上限 8)
}
var list = await db.Orders.Where(...).Project<OrderListItem>().ToListAsync(); // 表达式树直出,SQL 只取投影列
var mixed = db.Orders.Project<OrderListItem>(o => new OrderListItem { Total = o.Amount * 1.1m }); // 合并覆写
var item = order.ToProject<OrderListItem>(); // 内存投影
var entity = dto.ToEntity<Order>(); // DTO → 新实体(主键/并发戳自动排除)
entity.ApplyFrom(dto); // 就地更新
映射语义:同名匹配基底;无损转换自动(数值加宽/可空互包/bool↔int/任意→string/枚举档);string→数值等有损转换不自动(KLSG217 指路手写 Select)。严格度三级:显式单源缺省 Error、多源与无特性缺省 Warning、Skip 静默;全局经 LoomEfOptions.ProjectStrictness 覆盖。
查询规则引擎(ApplyRule)
动态条件白名单下推——完整契约见查询规则引擎:
var page = await db.Orders
.ApplyRule("status eq 'Active' and amount ge 100", catalog: catalog, sort: "createdAt desc")
.ToPagedAsync(1, 20);
动态视图([EfQuery])
[EfQuery("OrderRankView")] // 视图文件引用名(正道)——EfViews/*.sql 自动进编译
[EfEntity(typeof(Reporting))]
public sealed record OrderRankView
{
public string OrderNo { get; init; }
public int Rnk { get; init; }
}
视图文件首行 -- ef-view: OrderRankView 自我描述;也支持 const 引用与内联短 SQL。物化 HasNoKey().ToSqlQuery(sql)——EF 包子查询,Where/OrderBy/分页照常续写。视图进编译目录可评审:SQL 引租户表而无租户谓词 = KLSG222 提示,引用名无法解析 = KLSG223 Error。
批量插入(LoomBulkInsertAsync)
// 官方受管形态:雪花键预赋 + 分块 + 事务原子 + 逐块 SaveChanges
// 审计/watch/校验/提交门/租户/拦截器全部生效——不是 SqlBulkCopy 旁路
var inserted = await db.LoomBulkInsertAsync(orders, chunkSize: 1_000);
- 雪花键(单键
long)自动预赋,显式非 0 键尊重;实体须为 Detached(已跟踪 = 显式异常)。 - 无环境事务时自建事务包裹全部块(失败全回滚);UoW 内加入外层事务,由外层提交。
- 分块只控制单次
SaveChanges与跟踪器增长,不改变逐行 INSERT 成本;SqlBulkCopy/COPY 级吞吐需 provider 原生 API 并显式自担治理旁路(见声明与模型构建)。
二级缓存(ILoomSecondLevelCache)
缺省注册进程内内存适配(TTL 5 分钟 / 10,000 条);查询助手逐查询 opt-in:
var page = await db.Orders
.Where(o => o.State == OrderState.Open)
.LoomCachedToListAsync(db, cacheKey: $"open:{tenant}:{no}:{size}", timeToLive: TimeSpan.FromMinutes(1));
- 助手强制
AsNoTracking(),返回新List<T>(元素为缓存快照引用——只读消费,不得原地修改;修改列表本身不影响缓存,修改元素会污染缓存)。缓存键必须覆盖全部结果决定因素(谓词/参数/culture/租户)。 - 失效路径:SaveChanges 成功按变更实体(含基类)前缀自动失效;
LoomUpdateAsync/LoomDeleteAsync/LoomRestoreAsync同;SqlExecuteAsync全清。原生ExecuteUpdate/ExecuteDelete绕过 SaveChanges → 显式db.LoomInvalidateCache<Order>()(或LoomInvalidateAllCache())。 - 配置:
loom.SecondLevelCache.Enabled / MaxEntries / DefaultTimeToLive;Enabled = false且未注册自定义实现时查询助手 fail-fast(不静默降级为无缓存)。缓存为宿主级单例(首个启用注册生效;逐上下文选项只影响该单例的构造参数)。 - 替换:DI 注册自定义
ILoomSecondLevelCache整体替换内存适配;分布式实现须承载跨实例失效(RemoveByPrefix是失效协议的唯一必需操作)。 - 一致性边界:内存实现 per-process——多实例写不跨进程广播,仅适用于读多写少/可容忍 TTL 的数据;强一致读需求用分布式实现 + 短 TTL。缓存不是事务隔离级别,写后读仍由数据库/粘性窗保证。
受管批操作
// 谓词经 IQueryable 传入(自动追租户+软删);上下文作参——同库多上下文复用同一执法管线
await db.Orders.Where(o => o.Id == id).LoomUpdateAsync(db, s => s.SetProperty(x => x.Amount, 99m));
await db.Orders.Where(o => o.Id == id).LoomDeleteAsync(db); // 软删实体 = 批量逻辑删
await db.SqlQueryAsync<Row>($"SELECT Code FROM Labels WHERE Id = {id}"); // 参数化强制
- 受管写 API 强制主库路由、强制审计与租户谓词;只读上下文(
loom.ReadSplit.ReadOnly = true)与[EfReadOnly]实体同被拦截。 [EfWriteOnce]字段 SET 同拦(SQL 规则解析层恒拦——命令拦截器执行前解析 UPDATE SET 列集;原生ExecuteUpdate逃逸口与受管LoomUpdateAsync同拦、无旁路,见声明与模型构建)。
逃逸舱(原生口的白名单管制)
原生口 ExecuteDelete*/ExecuteUpdate*/SqlQuery*/FromSql* 缺省禁用:编译期 KLSG214 警告 + 运行时 Throw。确需开启:逐口显式白名单,开启后运行时降级为警告。
services.AddLoomEf<AppDbContext>(o => o.UseSqlServer(cs),
loom => loom.EscapeHatches(h => h.ExecuteUpdate().ExecuteDelete().SqlQuery()));
全局过滤器旁路 IgnoreQueryFilters 单独受 loom.QueryGuard.IgnoreQueryFiltersPolicy(缺省 Throw)管辖——见配置参考。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
IgnoreQueryFilters() 编译告警/运行抛异常 |
全量旁路连租户条件一并失效——系统核心不搭在旁路上 | 软删旁路用 IncludeDeletedScope();跨租户运维走中枢面 |
依赖 ExecuteDeleteAsync 直删 |
绕过逻辑删/审计/提交门/过滤器 | LoomDeleteAsync(软删实体自动转批量逻辑删) |
投影 DTO 成员引用了 [EfNotMapped] 属性 |
投影只见映射列——编译期 KLSG 提示 | DTO 源成员只映射真实列 |
| string→数值隐式依赖自动转换 | 有损转换不自动(KLSG217)——静默错值不可接受 | 手写 Select 显式转换 |
| 动态条件手拼 SQL 字符串 | 注入面 + 治理失控 | ApplyRule 白名单通道(查询规则引擎) |
AOT 边界(#209)
[Filterable] 生成目录的字段携带类型化 Accessor——ApplyFilter/ApplySort 命中访问器时不做按名属性反射,这是 AOT 快路径。
以下动态面标注 RequiresDynamicCode/RequiresUnreferencedCode,AOT 下必须改用生成 typed 面或显式关闭:
- 影子列查询
LoomShadowQueryExtensions(EF.Property<T>泛型构造); - 受管批写
LoomUpdateAsync/LoomRestoreAsync/LoomDeleteAsync与SqlQueryAsync; - 投影合并
LoomProjectionMerge.Merge(生成投影的部分覆写); - 手写
QueryFieldCatalog(无Accessor)的字段回退、JSON/影子字段、内存精筛、ApplySort/keyset 的动态表达式构造。
AOT 探针目前覆盖生成目录/EF 冻结模型路径;动态回退面以编译期警告指路,不承诺 NativeAOT 运行。
想深入
- 动态条件与 JSON 过滤:查询规则引擎 · ComplexType 与 JSON
- 多租户与软删的声明面:多租户与身份基座