ChanningMou.DataSearch 1.0.0.2

ChanningMou.DataSearch

高性能、通用、跨框架的 C# 数据查找 / 过滤引擎 —— 支持扁平数据、树形数据（保留结构）、流式输出与增量过滤，并内置表达式树条件构建器与编译期源生成器优化。

目录

• 特性一览
• 支持的框架
• 安装
• 快速开始
• 核心 API
• 条件表达式构建器
• 源生成器（自动优化）
• 性能
• 使用注意事项
• 版本与变更
• 许可

特性一览

支持的框架

所有框架功能完整，仅 net451 因运行时限制不导出流式 API 与源生成器。

安装

NuGet CLI

dotnet add package ChanningMou.DataSearch

PackageReference

<ItemGroup>
  <PackageReference Include="ChanningMou.DataSearch" Version="1.0.0" />
</ItemGroup>

引用本包即可，无需额外引用源生成器。源生成器 DLL 已打包进 analyzers/cs/，编译器会自动加载。

快速开始

1. 扁平数据过滤

using ChanningMou.DataSearch;

var data = Enumerable.Range(1, 100_000);

// 找出所有偶数（并行）
var evens = await DataSearchEngine.SearchFlatAsync(
    data,
    x => x % 2 == 0,
    parallel: true);

Console.WriteLine($"找到 {evens.Count} 个偶数");

2. 树形数据过滤（保留结构）

public class TreeNode
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<TreeNode> Children { get; set; } = new();
}

var roots = new List<TreeNode> { rootTree };

// 方式 A：自定义 createNode（最灵活、最快）
var filtered = await DataSearchEngine.SearchTreeAsync(
    roots,
    node => node.Id > 100,                 // 匹配条件
    node => node.Children,                 // 获取子节点
    (orig, children) => new TreeNode       // 构造新节点
    {
        Id = orig.Id,
        Name = orig.Name,
        Children = children.ToList()
    });

// 方式 B：不提供 createNode（内部自动深拷贝 + 替换 Children，更省心）
var filtered2 = await DataSearchEngine.SearchTreeAsync(
    roots,
    node => node.Id > 100,
    node => node.Children);

方式 B 会自动查找类型为 List<T>/IList<T>/ICollection<T> 的公共属性作为 Children；只读集合属性（实现 ICollection<T>）也支持（先 Clear() 再 AddRange()）。

3. 流式过滤（边过滤边返回）

// 扁平流式：逐条返回匹配项
await foreach (var item in DataSearchEngine.SearchFlatStream(
                   data, x => x % 2 == 0, parallel: true))
{
    Console.WriteLine(item);
}

// 树形流式：每过滤完一棵子树立即返回其新根
await foreach (var root in DataSearchEngine.SearchTreeStream(
                   roots,
                   node => node.Id > 100,
                   node => node.Children,
                   (orig, children) => new TreeNode { Id = orig.Id, Children = children.ToList() }))
{
    DisplayTree(root);
}

4. 增量过滤（数据源变化自动更新）

var observable = new ObservableCollection<TreeNode>(initialData);

using var filter = DataSearchEngine.CreateContinuousFilter(
    observable,
    node => node.IsActive,
    node => node.Children,
    (orig, children) => new TreeNode { Id = orig.Id, Children = children.ToList() });

filter.ResultChanged += (sender, newResult) => UpdateUI(newResult);

// 数据源变化时，filter 自动重算并触发事件
observable.Add(new TreeNode { ... });

5. 超时与取消

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(1));
try
{
    var result = await DataSearchEngine.SearchFlatAsync(
        data, x => x % 2 == 0, parallel: true, cancellationToken: cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("搜索超时");
}

核心 API

批量异步

// 扁平
Task<List<T>> SearchFlatAsync<T>(
    IEnumerable<T> data,
    Func<T, bool> predicate,
    bool parallel = false,
    CancellationToken cancellationToken = default);

// 树形（自定义 createNode）
Task<List<T>> SearchTreeAsync<T>(
    IEnumerable<T> roots,
    Func<T, bool> predicate,
    Func<T, IEnumerable<T>> getChildren,
    Func<T, IEnumerable<T>, T> createNode,
    bool parallel = false,
    CancellationToken cancellationToken = default) where T : notnull;

// 树形（自动深拷贝，T : class）
Task<List<T>> SearchTreeAsync<T>(
    IEnumerable<T> roots,
    Func<T, bool> predicate,
    Func<T, IEnumerable<T>> getChildren,
    bool parallel = false,
    CancellationToken cancellationToken = default) where T : class;

流式异步

IAsyncEnumerable<T> SearchFlatStream<T>(...);
IAsyncEnumerable<T> SearchTreeStream<T>(...);

增量过滤

public interface IIncrementalFilter<T> : IDisposable
{
    IReadOnlyList<T> CurrentResult { get; }
    event EventHandler<IEnumerable<T>> ResultChanged;
}

IIncrementalFilter<T> CreateContinuousFilter<T>(
    INotifyCollectionChanged source,
    Func<T, bool> predicate,
    Func<T, IEnumerable<T>>? getChildren = null,
    Func<T, IEnumerable<T>, T>? createNode = null);

条件表达式构建器

CreateFilterExpression / BuildPredicate 用策略模式自动为不同运算符组合选择最优表达式实现，避免大 N 时线性嵌套表达式编译栈溢出与性能下降。

策略矩阵

用法

// 单条件：Id in {1, 3, 5}
var predicate = DataSearchEngine.BuildPredicate<TreeNode, int>(
    node => node.Id,
    new[] { 1, 3, 5 },
    operand: ExpressionType.Equal,
    expressionType: ExpressionType.OrElse);

// 多条件 AND 组合：(Id in {1,3,5}) AND (Age >= 18) AND (Name != "")
var combined = DataSearchEngine.BuildCombinedPredicate<TreeNode>(
    new DataSearchEngine.ValueListCondition<TreeNode, int>(
        n => n.Id, new[] { 1, 3, 5 }),
    new DataSearchEngine.ValueListCondition<TreeNode, int>(
        n => n.Age, new[] { 18 }, ExpressionType.GreaterThanOrEqual),
    new DataSearchEngine.DirectCondition<TreeNode>(
        n => !string.IsNullOrEmpty(n.Name)));

var result = await DataSearchEngine.SearchFlatAsync(data, combined);

BuildPredicate / BuildCombinedPredicate 返回的 Func<T, bool> 可直接传给 SearchFlatAsync / SearchTreeAsync 的 predicate 参数。

源生成器（自动优化）

当调用无 createNode 参数的 SearchTreeAsync / SearchTreeStream 重载时，编译期源生成器会：

1. 扫描调用点，收集节点类型 T；
2. 为每个 T 生成强类型工厂 DataSearchCreateNodeFactory<T>，其 Create 字段即 Func<T, IEnumerable<T>, T>；
3. 生成 [assembly: DataSearchGenerateCreateNode(typeof(T))] 特性；
4. 运行时 BuildDefaultCreateNode<T> 三级回退：源生成器 → IL Emit → 表达式树。

消费者无需任何额外配置，引用 DataSearch 包即可自动启用。net451 因运行时限制不支持源生成器，会自动回退到 IL Emit / 表达式树路径，功能完整。

性能

测试环境：Intel i7-10700, 16GB RAM, .NET 8.0

优化要点

• NodeState<T> 在 .NET 5+ 为 struct，零堆分配；用 ref 访问字典条目避免值拷贝。
• 树形过滤用非递归显式栈遍历，杜绝栈溢出；标记-重建自底向上，保留结构。
• 多根节点并行用 Parallel.ForEach，扁平用 PLINQ。
• 条件表达式按策略选择 HashSet.Contains / Min/Max / 平衡树，避免大 N 线性嵌套。
• BuildDefaultCreateNode<T> 委托按类型缓存于 ConcurrentDictionary，仅首次反射。

使用注意事项

版本与变更

详见 CHANGELOG.md。

依赖

• Channing.Cloner —— 深拷贝（无 createNode 重载使用）
• Microsoft.Bcl.AsyncInterfaces —— IAsyncEnumerable<T> polyfill（仅 netstandard2.0 / netcoreapp2.0）
• System.ValueTuple —— 元组语法（仅 net451）

作者与联系方式

• 作者: ChanningMou (牟成贵)
• 公司: ChanningMou
• 邮箱: 2538777526@qq.com

如有问题、建议或商业合作，欢迎通过邮箱联系，或提交 Issue / Pull Request。

许可

MIT License

Copyright (c) 2026 ChanningMou (牟成贵)