查询字段目录(Filterable)
定位
KernLab.Loom.Query——[Filterable] 查询字段目录源生成:DTO/契约属性标注 → 编译期物化 {契约名}FilterIndex 强类型白名单目录(字段名 → 类型化访问器 + 允许操作符集 + 值类型),零反射消费(白名单校验 / 表达式构建 / 补全 schema 同一数据面),NativeAOT 安全。它是查询规则引擎的字段暴露面——目录里没有的字段,动态条件到不了 SQL。
快速上手
using KernLab.Loom;
using KernLab.Loom.Ef;
public sealed record OrderFilter
{
[Filterable]
public string? OrderNo { get; init; }
[Filterable(Operators = FilterOperators.Equal | FilterOperators.GreaterThanOrEqual | FilterOperators.LessThanOrEqual)]
public decimal Amount { get; init; }
[Filterable]
public DateTime CreatedAt { get; init; }
[Filterable(Sortable = false)] // 可过滤、不可排序
public string? InternalNote { get; init; }
public string Secret { get; init; } = ""; // 未标注 = 不进目录(不可查)
}
生成物:OrderFilterFilterIndex——字段名 → 类型化访问器 + 操作符集 + 值类型;SchemaJson 属性直出补全/校验 schema(逐字段含 sortable 标记);ToCatalog() 返回运行时字段目录(见下)。目录项带 Sortable 标志(缺省 true——可过滤即可排序;false 只进过滤面)。
运行时接线(零反射)
// 编译期目录 → 运行时白名单(缓存单例;需要引用 KernLab.Loom.Query.Runtime)
var catalog = OrderFilterFilterIndex.ToCatalog();
// DSL/JSON 解析与 EF 绑定共用同一目录:目录外字段在解析期即拒(QR001)
var page = await db.Orders.ApplyRule("amount ge 100 and orderNo contains 'A'", catalog).ToPagedAsync(1, 20);
ToCatalog() 的字段集与 [Filterable] 标注面严格一致——未标注属性不可查(运行时目录 =
编译期目录)。消费者未引用 KernLab.Loom.Query.Runtime 时该成员不发射(其余生成物仍 BCL-only)。
兼容入口 QueryFieldCatalog.Build(Type)([Obsolete])保留反射基线,仅用于老代码;
它收录全部公开属性,口径宽于 [Filterable] 白名单——新代码不要使用。该入口也会读取
属性级 [Filterable(Sortable = false)] 与 [FilterField(..., Sortable = false)](不新增反射入口);
但它不处理类级 [Filterable("X")](Operator/Sortable 均同——既有反射口径差),且白名单口径仍宽于
标注面。迁移 ToCatalog() 后此入口再升 error 级弃用。
概念与术语
- 字段目录(FilterIndex):编译期物化的白名单——动态查询唯一合法的字段暴露面。
- 操作符集(FilterOperators):逐字段声明的允许操作符位组合(eq/ne/gt/ge/lt/le/contains/startswith/endswith/in/isnull/isnotnull 等)——目录即能力边界。
- Schema:目录的 JSON 形态(字段/类型/
sortable排序标记/操作符协议码)——/query-schema端点直出,前端补全/排序菜单同源。 - Sortable:目录项的排序白名单标志——缺省
true;[Filterable(Sortable = false)]只允许过滤,排序段/ApplySort一律 QR007 拒绝。 - 点路径字段:
元数据.层级形态——ComplexType 成员自动派生或[FilterField]显式声明 JSON 路径(见 EF 文档 ComplexType 与 JSON)。点路径字段继承声明处的Sortable。
怎么选
| 方案 | 优势 | 代价 | 适用场景 |
|---|---|---|---|
| [Filterable] 目录 | 编译期白名单零反射;schema 同源;AOT 安全 | 新可筛字段须显式进目录 | 动态条件查询的字段暴露(本组件) |
| 手写白名单 switch | 零依赖 | 逐字段爆炸;类型安全无保障;schema 手维护 | 单点一次性筛选 |
| 运行时反射扫描 | 零声明 | 反射开销 + AOT 不友好 + 白名单失控 | 不推荐(Build(Type) 已弃用) |
决策:动态条件面用目录(暴露面可控是价值不是负担);固定查询不需要目录。
怎么用
声明字段
[FilterField(name, valueType, operators)]——name 是对外暴露的字段名(点路径合法);valueType 决定值翻译;operators 是允许操作符位组合。
排序白名单(Sortable)
排序白名单是过滤目录的子集,由 [Filterable(Sortable = false)] 逐字段收紧(属性级/类级均适用):
[Filterable]
public string OrderNo { get; init; } = ""; // 可过滤 + 可排序(缺省)
[Filterable(Sortable = false)]
public string? InternalNote { get; init; } // 可过滤,排序段拒绝(QR007)
- 缺省
true保持既有"可过滤即可排序"行为;显式false才收缩排序面(无静默收窄)。 QuerySort.Parse与ApplySort双闸执法:未登记字段 = QR001,目录内但Sortable = false= QR007 (与过滤的"未知字段/操作符越界"同形,QueryRuleException结构化码)。- 排序字段大小写不敏感;解析结果回写目录规范字段名。
- 点路径字段(
[EfComplex]派生)继承根属性的Sortable。 - 影子字段(
[FilterField],反射目录)用Sortable = false同口径声明。
能力标记与 Schema 消费
Mode(FilterFieldMode——SQL 直译/内存求值档声明)与 JsonColumn(JSON 文档列绑定)——JSON 形态语义见 EF ComplexType 与 JSON。
FilterIndex.SchemaJson / LoomQueryRegistry.SchemaJsonOf(name)——契约清单与逐契约 schema(逐字段
field/type/sortable/ops);前端下拉、校验与排序菜单直接消费,无需手工同步。
复杂类型目录自动派生
值对象标 [EfComplex] 后嵌套标量成员自动进目录与 Schema(业务无需逐成员声明;显式 [FilterField] 可覆盖操作符)——见 EF 声明与模型构建。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 动态条件查不到某字段(QR001) | 目录白名单外——这是特性不是缺陷 | 字段进 [FilterField] 目录 |
| 把值类型标错 | 值翻译按 ValueType 走——错型 = QR003 转换失败 | ValueType 与存储类型一致 |
| 目录字段承载业务流程判断 | 目录是数据筛选暴露面,不是业务规则引擎 | 业务判断在领域层 |
| 排序字段不进目录 | 排序段同白名单执法 | 排序字段显式声明进目录 |
| 大字段/内部字段能过滤就顺带可排序 | 排序白名单默认继承过滤面(历史行为),不该排序的字段会被前端暴露 | 标注 [Filterable(Sortable = false)] 收紧排序面 |
绕过目录直接 ApplySort(sorts) |
无目录 = 无白名单(排序面失控) | ApplySort(sorts, catalog) 必填 |
分页与投影(#147)
- offset 分页:
QueryPageRequest+ApplyPage(PageSize上限 200,总数调用方并行取)。 - keyset/cursor 分页:
ApplyKeyset(sorts, catalog, anchorField, after)(自带排序)+QueryCursor编解码。 锚字段由调用方显式声明(必须是排序链末位,数据层保证唯一);游标格式base64url(UTF8(JSON{"v":1,"k":[...]}))(invariant 键值、版本 v1、长度/键值数上限)。 越界契约:锚不在目录 QR001、不可排序 QR007、锚非末位/影子或 JSON 字段/null 键值 QR009、 游标非法 QR008。边界:排序键非空与跨 provider collation 一致性由调用方保证(详见 查询规则引擎)。 - 投影:
ApplyProjection(expr)官方组合子(=IQueryable.Select,不重复 EfProject<T>物化契约); 顺序 = 过滤 → 排序 → 分页 → 投影,投影后排序用投影 DTO 自己的字段/LINQ,不复用实体目录。
想深入
- 消费侧(表达式树直出/复杂度护栏/JSON 负载):EF 查询规则引擎
- API 参考:docs.kernlab.dev/loom/api
性能
量化基线:rule-parse-baseline.md。