Table of Contents

查询规则引擎

前端/API 传来的动态条件怎么安全下推成 SQL:字段目录白名单、DSL/JSON 双语法、复杂度护栏、字典翻译缝与数据范围缝。 上位:总览。

定位

即席查询(列表筛选/报表条件/高级搜索)的传统实现是字符串拼 SQL 或手写表达式分支——前者注入面失控,后者逐字段爆炸。查询规则引擎把动态条件收敛为一条编译期白名单通道:字段目录编译期物化 → 条件解析即校验 → 表达式树直出,全局过滤器/租户执法/慢 SQL 监控照常全覆盖(规则查询 = 普通 IQueryable 组合,零特殊处理)。

字段目录([Filterable])

public sealed record OrderFilter
{
    [Filterable(Operators = FilterOperators.Eq | FilterOperators.Contains)]
    public string OrderNo { get; init; } = "";

    [Filterable(Operators = FilterOperators.Ge | FilterOperators.Le)]
    public decimal Amount { get; init; }

    [Filterable(Operators = FilterOperators.Le)]
    public DateTime CreatedAt { get; init; }

    [Filterable(Sortable = false)]      // 可过滤、排序段 QR007 拒绝
    public string? InternalNote { get; init; }
}
  • 标注形态:属性级 [Filterable(Operators = ...)](主形态);类级形态为 [Filterable("成员名")](成员缺失 = KLSG110)。Operators = None = 按字段类型取默认操作符集。
  • 包引用:引 KernLab.Loom.Ef.Runtime 即随包携带 KernLab.Loom.Query 分析器(#82——无需额外包;漏引会静默零产物 CS0103)。
  • 物化 {契约名}FilterIndex 强类型字段目录:字段名 → 类型化访问器 + 允许操作符集 + 值类型 + Sortable——零反射消费。
  • 排序白名单 = 目录子集:缺省 Sortable = true(可过滤即可排序,保持既有行为);[Filterable(Sortable = false)] 只收缩排序面(#147)。QuerySort.Parse / ApplySort 双闸:未知字段 QR001、不可排序字段 QR007。
  • 编译期 Schema:LoomQueryRegistry(契约清单 + SchemaJsonOf(name))与各 FilterIndex.SchemaJson——逐字段含 sortable 标记;/query-schema 端点直接取用,补全/校验/排序菜单前端同源。
  • 运行时目录用 {契约名}FilterIndex.ToCatalog()(编译期白名单零反射);反射式 QueryFieldCatalog.Build(Type) 仅为兼容入口([Obsolete],收全部公开属性——宽于白名单,勿在新代码使用)。
  • ComplexType 字段自动派生:值对象类型标 [EfComplex] 后,嵌套标量成员自动进目录与 Schema(点路径字段 = 成员访问链 typed 访问器,如 地址.城市)——业务无需逐成员声明,见ComplexType 与 JSON。

DSL 与分步形态

// DSL:15 算子 eq/ne/gt/ge/lt/le/contains/startswith/endswith/in/isnull/isnotnull/not/and/or
// ——大小写不敏感别名 + 符号别名双入口
var page = await db.Orders
    .ApplyRule("status eq 'Active' and amount ge 100", catalog: catalog, sort: "createdAt desc")
    .ToPagedAsync(1, 20);

// 分步形态(条件/排序/分页各自可用——ApplySort 的目录参数必填,白名单不可旁路)
var q = db.Orders.ApplyFilter(condition, catalog, scopeProvider: charterScope);
q = q.ApplySort(sorts, catalog);
var rows = q.ApplyPage(new QueryPageRequest(1, 20));

JSON 负载(QueryRuleJson——API 形态)

// 请求负载(POST /orders/search 的 body 片段)
{
  "filter": {
    "op": "and",
    "nodes": [
      { "field": "status", "op": "eq", "value": "Active" },
      { "field": "amount", "op": "ge", "value": 100 },
      { "op": "or", "nodes": [
          { "field": "code", "op": "in", "values": ["A", "B"] },
          { "field": "remark", "op": "isnull" }
      ]}
    ]
  },
  "orderBy": "createdAt desc",
  "page": 1, "pageSize": 20
}
// 服务端:JSON → 条件树 → 表达式树(与 DSL 同一出口,白名单/翻译缝/范围缝全同)
var condition = QueryRuleJson.Parse(json, catalog, new QueryComplexityOptions
{
    MaxTextLength = 8_000,   // 负载长度上限
    MaxDepth = 8,            // 嵌套深度上限——防恶意深树
    MaxConditions = 200,     // 叶子条件上限
});
var rows = await db.Orders
    .ApplyFilter(condition, catalog, scopeProvider: charterScope)
    .ApplySort(QuerySort.Parse(orderBy, catalog), catalog)
    .ApplyPage(new QueryPageRequest(page, pageSize))   // PageSize 上限 200,Normalized 归一
    .ToListAsync();

// 回写(导出已存规则/回显给前端)
string json = QueryRuleJson.Write(condition);

绑定语义

  • 白名单:过滤字段过目录(未知字段 = QR001);排序段过目录 + Sortable(未登记 = QR001、不可排序 = QR007)。排序字段大小写不敏感,绑定按目录规范名直构。
  • 值翻译两问:先问字典翻译缝(IDictionaryValueTranslator——字典编码字段如显示名→存储码),未翻译再走类型驱动字面量转换(enum/DateTime/DateOnly/Guid/decimal 及可空;失败 = QR003)。
  • 数据范围缝(IDataScopeProvider——Charter 承载):条件与动态条件自动 AndAlso,范围永不被绕过。
  • 解析即校验:复杂度上限(长度/深度/叶子数)防畸形负载拖库;错误统一 QueryRuleException(QR001 未知字段 / QR003 值转换失败 / QR007 字段不可排序 / QR008 游标非法 / QR009 keyset 契约不满足 / 超限各自带定位信息)——ASP.NET Core 侧经 ProblemDetails 中间件直接映射 400。
  • 全局覆盖照常:租户/软删过滤器、逃逸舱双闸、慢 SQL 监控对规则查询全量生效。

keyset 分页与投影(#147)

keyset/cursor 分页(稳定排序上的"游标之后"查询)

var sorts = QuerySort.Parse("createdAt desc, id asc", catalog);   // 末位 = 调用方声明的唯一锚

// 第一页(ApplyKeyset 自带排序)
var page1 = await db.Orders
    .ApplyFilter(condition, catalog, scopeProvider: charterScope)
    .ApplyKeyset(sorts, catalog, anchorField: "Id")
    .Take(20)
    .ToListAsync();

// 下一页:上一页末行的排序链键值(顺序与 sorts 一致)
var cursor = QueryCursor.FromValues(page1[^1].CreatedAt, page1[^1].Id);
var page2 = await db.Orders
    .ApplyFilter(condition, catalog, scopeProvider: charterScope)
    .ApplyKeyset(sorts, catalog, anchorField: "Id", after: cursor)
    .Take(20)
    .ToListAsync();
  • 锚唯一性调用侧显式声明:anchorField 必须等于排序链末位字段(大小写不敏感归一),数据层保证唯一; 框架不校验数据唯一性(目录不承载 Unique 元数据)。
  • 运行期校验:排序链空/锚不是末位/影子或 JSON 字段/bool·enum 键 = QR009 KeysetContractViolated; 锚未登记 = QR001;锚不可排序 = QR007;游标键值数不符 = QR008。
  • 游标格式:base64url(UTF8(JSON{"v":1,"k":[...]}));键值 invariant(string 原样、DateTime/Offset "O"、 Guid "D"、bool true/false);长度 ≤8192、键值数 ≤32、版本不支持/形态非法 = QR008 CursorInvalid; null 键值 = QR009。
  • 谓词:多字段字典序 OR((a > va) OR (a = va AND b > vb) …),降序方向跟随排序链;单字段锚即可用。
  • 边界:排序键非空由调用方保证(游标拒绝 null);字符串/Guid 比较依赖 provider collation/排序, 与 ORDER BY 同源,跨 provider 一致性由调用方保证;TimeSpan 等类型的 ORDER BY 支持随 provider (如 SQLite 不支持)——与既有 ApplySort 同一 provider 能力面(§3.3.3 #147)。

投影(官方 IQueryable 组合子)

var rows = await db.Orders
    .ApplyFilter(condition, catalog)
    .ApplySort(sorts, catalog)
    .ApplyPage(new QueryPageRequest(1, 20))
    .ApplyProjection(o => new OrderListItem { Id = o.Id, Amount = o.Amount })
    .ToListAsync();
  • 组合顺序契约 = 过滤 → 排序 → 分页 → 投影;ApplyProjection = IQueryable.Select(EF 翻译), 上游排序/页在投影后仍成立(行为测试锁定)。
  • 与 Ef 面 [EfProject]/Project<T> 分工:后者是编译期 DTO 契约/物化映射;本组合子只做 IQueryable 组合。
  • 投影后排序用投影 DTO 自己的字段目录/LINQ(实体目录字段名/语义不再对应)。

JSON 负载字段(JSON 列查询)

字段目录绑定 JSON 文档列([FilterField(JsonColumn=)] 或 [EfComplex] 派生)后,点路径字段(元数据.层级)走同一通道。JSON 形态的翻译能力与内存模式护栏见ComplexType 与 JSON 的「JSON 查询三层」——重过滤成员应选多列形态(全 provider 一致 + 可索引),JSON 路径过滤定位 = 轻量补充。

反模式

症状 为什么错 正确形态
前端传什么字段就查什么字段 白名单外字段 = QR001 是特性不是缺陷——目录就是暴露面 新可筛字段进 [Filterable] 目录,不放开旁路
把业务判断塞进查询规则(余额够不够) 规则引擎是字段值域过滤,不是业务流程判断 业务判断在领域层,规则引擎只做数据筛选
复杂度上限调到无限大 MaxDepth/MaxConditions 是拖库防线 按真实前端形态给裕量,不做无界
把不该排序的字段放进目录 缺省 Sortable = true——进目录即可被排序(历史行为) 标注 [Filterable(Sortable = false)] 收紧排序面
绕过目录调 ApplySort(sorts) 无目录 = 排序白名单失控(且无法区分不可排序字段) ApplySort(sorts, catalog)——目录参数必填
跨环境行为不一致的"自动降级" 同一规则在不同环境翻译能力不同 = 行为漂移 JSON 内存模式显式声明(Mode = Memory),不做自动降级

想深入