Table of Contents

查询与投影

过滤器族怎么自动生效、影子列怎么查、分页、投影映射、动态视图、受管批操作与逃逸舱。 动态条件的安全下推见查询规则引擎。

可运行 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 运行。

想深入