过滤条件构建（`DynamicFilter` 与 `FilterBuilder`）

DynamicFilter 是 Chameleon 平台通用的动态查询条件模型（定义于 Chameleon.Common.Models，又称"动态过滤条件 / 查询条件 / where 条件"），用于 IChameleonDbContext 的 GetList / GetCount / IsExist 等查询方法。FilterBuilder 是平台提供的静态工厂类（Chameleon.Database 命名空间），用于以代码方式便捷构建 DynamicFilter。

概述

DynamicFilter 是一棵条件树：叶子节点是「字段 + 操作符 + 值」，非叶子节点通过 Logic（And / Or）组合子条件。它同时被以下场景复用：

SDK 的 DbContext 查询（本文档）
平台接口查询列表组件的过滤参数
视图列表等前端查询条件（存储格式见查询操作符规约）

推荐始终用 FilterBuilder 构建条件，而不是手写 new DynamicFilter { ... }，可避免操作符枚举写错。

DynamicFilter 模型属性

属性	类型	含义	取值
`Field`	`string`	字段编码	一律使用小写；会被转为小写并做 SQL 注入校验
`Operator`	`FilterOperator`	操作符	见下方操作符表
`Value`	`object`	比较值	类型随操作符而定
`ValueType`	`FilterValueType`	值类型提示	`Default=0` / `String=1` / `Number=2` / `DateTime=3` / `Boolean=4` / `Guid=5`，默认 `Default`
`Logic`	`FilterLogic`	子条件逻辑	`And=0` / `Or=1`
`Filters`	`List<DynamicFilter>`	子条件列表	与当前节点为 `And` 关系

操作符总表

FilterOperator 枚举与 FilterBuilder 工厂方法的对应关系（取值以后端枚举为准）：

语义	`FilterBuilder` 方法	`FilterOperator`	存储值	`Value` 要求
等于	`Eq(field, value)`	`Eq`	`9`	任意
不等于	`Ne(field, value)`	`Ne`	`10`	任意
大于	`Gt(field, value)`	`Gt`	`11`	可比较类型
大于等于	`Gte(field, value)`	`Gte`	`12`	可比较类型
小于	`Lt(field, value)`	`Lt`	`13`	可比较类型
小于等于	`Lte(field, value)`	`Lte`	`14`	可比较类型
包含（like %v%）	`Contains(field, value)`	`Ct`	`1`	字符串
不包含	`NotContains(field, value)`	`Nct`	`4`	字符串
前缀匹配	`StartsWith(field, value)`	`Sw`	`2`	字符串
非前缀匹配	`NotStartsWith(field, value)`	`Nsw`	`5`	字符串
后缀匹配	`EndsWith(field, value)`	`Ew`	`3`	字符串
非后缀匹配	`NotEndsWith(field, value)`	`New`	`6`	字符串
在集合中	`In(field, value)`	`In`	`17`	逗号分隔字符串或数组
不在集合中	`NotIn(field, value)`	`Nin`	`18`	逗号分隔字符串或数组
数组包含（PostgreSQL `@>`）	`Act(field, value)`	`Act`	`19`	必须传 `string[]` 或 `int[]`，不支持逗号分隔字符串
取全量安全条件	`FilterBuilder.Empty`（静态属性）	`Ne`	`10`	等价于 `_id != Guid.Empty`

组合方法：

static DynamicFilter And(params DynamicFilter[] filters);  // 生成 Logic = And 的父节点
static DynamicFilter Or(params DynamicFilter[] filters);   // 生成 Logic = Or 的父节点

使用示例

单条件

var filter = FilterBuilder.Eq("status", "Pending");
var list = await sdk.DbContext.GetListAsync("LeaveApplication", filter);

And 组合多条件

var filter = FilterBuilder.And(
    FilterBuilder.Eq("isdeleted", false),
    FilterBuilder.Gte("amount", 1000),
    FilterBuilder.Contains("orderno", "SO2026")
);

Or 与嵌套组合

// (status = 'Approved' OR status = 'Rejected') AND isdeleted = false
var filter = FilterBuilder.And(
    FilterBuilder.Or(
        FilterBuilder.Eq("status", "Approved"),
        FilterBuilder.Eq("status", "Rejected")
    ),
    FilterBuilder.Eq("isdeleted", false)
);

In 与数组包含

// In：逗号分隔字符串或数组均可
var inFilter = FilterBuilder.In("status", "Pending,Approved");
var inFilter2 = FilterBuilder.In("_id", someGuidArray);

// Act（数组字段包含）：必须传数组，传逗号分隔字符串会抛 ArgumentException
var actFilter = FilterBuilder.Act("tags", new[] { "vip", "oversea" });

手写 DynamicFilter（不推荐但合法）

var filter = new DynamicFilter
{
    Logic = FilterLogic.And,
    Filters = new List<DynamicFilter>
    {
        new() { Field = "status", Operator = FilterOperator.Eq, Value = "Pending" },
        new() { Field = "isdeleted", Operator = FilterOperator.Eq, Value = false }
    }
};

JSON 存储示例

DynamicFilter 序列化为 JSON 后的存储/传输格式（接口传参、元数据存储位置均使用此结构）：

{
  "Field": "amount",
  "Operator": "Gte",
  "Value": 1000,
  "ValueType": "Default",
  "Logic": "And",
  "Filters": [
    { "Field": "status", "Operator": "Eq", "Value": "Completed", "ValueType": "Default", "Logic": "And", "Filters": null }
  ]
}

行为细节与异常

字段名转小写：Field 会被 ToLowerInvariant() 后参与 SQL 生成，建议编码时就用小写
SQL 注入校验：字段名经 ValidateSqlInjection 校验，含非法字符抛 ArgumentException
ValueType 类型转换：ValueType 非 Default 时会尝试将 Value 转换为目标类型（如 "2026-01-01" 转 DateTime），转换失败抛 ArgumentException
Act 操作符：由自定义过滤器翻译为 PostgreSQL 的 field @> ARRAY[...]；空值生成恒假条件 1 = 2；值中的单引号会被转义防注入
无条件查询全表：用 FilterBuilder.Empty，禁止向需要过滤条件的方法传 null

下一步

条件查询与分页 - 把过滤条件用于查询方法
查询操作符规约 - 平台通用查询操作符与前端传参格式
数据查询与分页组件 - 可视化编排中的条件传参

概述​

DynamicFilter 模型属性​

操作符总表​

使用示例​

单条件​

And 组合多条件​

Or 与嵌套组合​

In 与数组包含​

手写 DynamicFilter（不推荐但合法）​

JSON 存储示例​

行为细节与异常​

下一步​

相关实现​

概述