查询规则引擎
前端/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"、booltrue/false);长度 ≤8192、键值数 ≤32、版本不支持/形态非法 = QR008CursorInvalid; 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),不做自动降级 |
想深入
- JSON 列与值对象:ComplexType 与 JSON
- 过滤器/分页基元:查询与投影