TJC.Cyclops.Linq 2026.1.15.1

Cyclops.Linq

项目概述

Cyclops.Linq是企服版框架中的LINQ扩展库，提供了丰富的LINQ扩展方法和查询工具，用于增强.NET标准LINQ功能，简化复杂数据查询和转换操作。该项目旨在解决企业应用开发中常见的数据处理需求，提供更强大、更灵活、更易用的数据查询能力。Cyclops.Linq包含集合操作、查询优化、延迟执行增强、特殊数据结构支持等多个功能模块，为开发者提供了全面的LINQ增强工具集。

核心功能模块

1. 集合操作扩展

1.1 过滤操作

• WhereIf：条件过滤，根据布尔值决定是否应用过滤条件
• WhereNot：排除符合条件的元素，Where的反操作
• WhereNotNull：过滤掉空值元素
• WhereNotEmpty：过滤掉空集合或空字符串
• WhereBetween：过滤指定范围内的元素
• WhereIn：过滤包含在指定集合中的元素
• WhereNotIn：过滤不包含在指定集合中的元素
• WhereDistinct：根据指定条件去重过滤

1.2 排序操作

• OrderByCaseInsensitive：不区分大小写的排序
• OrderByRandom：随机排序
• OrderByPriority：基于优先级规则的排序
• OrderByCustom：自定义排序规则
• ThenByCaseInsensitive：不区分大小写的二次排序

1.3 投影操作

• SelectWithIndex：带索引的投影，将索引作为参数传入
• SelectIf：条件投影，根据布尔值决定是否应用投影
• SelectManyWithIndex：带索引的多级投影
• SelectDistinct：投影并去重
• SelectWithExceptionHandling：带异常处理的投影

2. 查询优化

2.1 性能优化

• Batch：批量处理集合，将大集合分割成小批次处理
• Chunk：将集合分割成固定大小的块
• TakeUntil：获取元素直到满足特定条件
• SkipUntil：跳过元素直到满足特定条件
• FirstOrDefaultAsync：异步获取第一个元素或默认值
• SingleOrDefaultAsync：异步获取单个元素或默认值
• AnyAsync：异步检查是否包含元素
• CountAsync：异步计算元素数量

2.2 延迟执行增强

• Materialize：强制立即执行延迟查询
• Cache：缓存查询结果以提高性能
• Memoize：记忆化查询结果，避免重复计算
• Defer：延迟查询构造直到需要时
• EvaluateWhen：条件执行查询

3. 聚合操作

3.1 统计计算

• AverageOrDefault：计算平均值，如果集合为空则返回默认值
• SumOrDefault：计算总和，如果集合为空则返回默认值
• MaxOrDefault：获取最大值，如果集合为空则返回默认值
• MinOrDefault：获取最小值，如果集合为空则返回默认值
• Median：计算中位数
• Mode：计算众数
• Percentile：计算百分位数
• StandardDeviation：计算标准差
• Variance：计算方差

3.2 集合操作

• Merge：合并多个集合
• ZipMany：合并多个集合的对应元素
• Interleave：交错合并多个集合
• Difference：计算集合差集
• Intersection：计算集合交集
• UnionDistinct：计算集合并集（去重）
• SymmetricDifference：计算集合对称差集
• ContainsAll：检查是否包含指定集合中的所有元素
• ContainsAny：检查是否包含指定集合中的任一元素

4. 特殊数据结构支持

4.1 树形结构

• AsHierarchy：将扁平集合转换为层次结构
• FlattenHierarchy：将层次结构扁平化为集合
• TraverseDepthFirst：深度优先遍历树形结构
• TraverseBreadthFirst：广度优先遍历树形结构
• FindDescendants：查找所有后代元素
• FindAncestors：查找所有祖先元素
• Level：获取元素在树形结构中的层级

4.2 分组操作

• GroupByMulti：多级分组
• GroupByRange：按范围分组
• GroupByDateTime：按日期时间分组（年、月、日等）
• GroupByKeySelector：动态分组
• GroupByCaseInsensitive：不区分大小写的分组
• GroupByEqualityComparer：使用自定义相等比较器分组

5. 数据转换

5.1 类型转换

• OfTypeOrEmpty：按类型筛选，如果没有匹配则返回空集合
• CastSafe：安全转换类型，失败时返回默认值
• ConvertAll：将集合中的所有元素转换为指定类型
• ToDictionarySafe：安全地转换为字典，处理重复键
• ToLookupSafe：安全地转换为查找表，处理重复键

5.2 集合转换

• ToPagedList：将集合转换为分页列表
• ToDataTable：将集合转换为DataTable
• ToJson：将集合序列化为JSON字符串
• ToCsv：将集合转换为CSV格式字符串
• ToXml：将集合转换为XML格式字符串
• ToObservableCollection：将集合转换为可观察集合

6. 特殊操作

6.1 条件操作

• IfEmpty：如果集合为空则返回替代集合
• IfSingle：如果集合只有一个元素则应用特殊处理
• IfMultiple：如果集合有多个元素则应用特殊处理
• ElseIf：条件链处理
• ThenByCondition：条件性二次排序

6.2 循环和索引

• ForEachIndex：带索引的遍历
• ForEachParallel：并行遍历集合
• ForEachWithTimeout：带超时的遍历
• ForEachUntil：遍历直到满足特定条件
• TakeLast：获取集合的最后N个元素
• SkipLast：跳过集合的最后N个元素
• FirstIndexOf：查找第一个匹配元素的索引
• LastIndexOf：查找最后一个匹配元素的索引

7. 高级查询

7.1 窗口函数

• Window：滑动窗口操作
• RollingAverage：滚动平均值计算
• RollingSum：滚动总和计算
• RollingMax：滚动最大值计算
• RollingMin：滚动最小值计算

7.2 集合分区

• PartitionBy：根据条件将集合分区
• Split：将集合拆分为多个部分
• SplitWhen：当满足条件时拆分集合
• SplitIntoChunks：将集合拆分为固定大小的块
• ChunkBy：根据键选择器将集合分块

8. 异步操作

8.1 异步LINQ

• WhereAsync：异步过滤
• SelectAsync：异步投影
• OrderByAsync：异步排序
• GroupByAsync：异步分组
• AnyAsync：异步检查是否包含元素
• AllAsync：异步检查是否所有元素都满足条件
• CountAsync：异步计算元素数量
• SumAsync：异步计算总和
• AverageAsync：异步计算平均值

8.2 异步集合操作

• ToListAsync：异步转换为列表
• ToArrayAsync：异步转换为数组
• ToDictionaryAsync：异步转换为字典
• ForEachAsync：异步遍历集合
• ParallelForEachAsync：并行异步遍历集合
• WhenAllAsync：异步等待所有操作完成

9. 功能扩展

9.1 范围操作

• ForEachBetween：在指定范围内遍历
• SelectBetween：在指定范围内投影
• TakeWhileInclusive：获取元素直到满足条件（包括满足条件的元素）
• SkipWhileInclusive：跳过元素直到满足条件（包括满足条件的元素）

9.2 安全操作

• FirstOrEmpty：获取第一个元素或空集合
• LastOrEmpty：获取最后一个元素或空集合
• ElementAtOrEmpty：获取指定索引的元素或空集合
• SingleOrEmpty：获取单个元素或空集合
• DefaultIfEmptySafe：安全地提供默认值（处理null）
• TryGetValue：尝试获取值，避免异常

10. 数据验证

10.1 集合验证

• IsEmptyOrNull：检查集合是否为空或null
• IsNullOrEmpty：检查集合或字符串是否为空或null
• IsSingle：检查集合是否只有一个元素
• IsMultiple：检查集合是否有多个元素
• HasDuplicates：检查集合是否有重复元素
• IsSorted：检查集合是否已排序
• IsDistinct：检查集合是否所有元素都唯一

10.2 元素验证

• AllNotNull：检查所有元素是否都不为null
• AllNotDefault：检查所有元素是否都不是默认值
• AnyNotNull：检查是否有元素不为null
• AnyNotDefault：检查是否有元素不是默认值

技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • System.Linq - 用于基础LINQ操作
  • System.Collections.Generic - 用于集合操作
  • System.Linq.Expressions - 用于表达式树操作
  • System.Threading.Tasks - 用于异步操作
  • Newtonsoft.Json - 用于JSON序列化（可选）
  • System.Data - 用于DataTable转换（可选）

环境依赖要求

• .NET 8.0 SDK 或更高版本
• 对于JSON转换功能，需要Newtonsoft.Json包
• 对于DataTable转换功能，需要System.Data.Common包

安装与配置

安装方式

可以通过以下方式安装Cyclops.Linq包：

1. NuGet包管理器：

   Install-Package TJC.Cyclops.Linq
   

2. .NET CLI：

   dotnet add package TJC.Cyclops.Linq
   

配置方法

Cyclops.Linq作为扩展方法库，无需特殊配置，只需在使用时引入命名空间即可：

using Cyclops.Linq;

核心功能代码示例

1. 条件过滤示例

// 基本条件过滤
var activeUsers = users.WhereIf(isActive, u => u.IsActive);

// 多条件过滤
var filteredUsers = users
    .WhereIf(filterByName, u => u.Name.Contains(searchName))
    .WhereIf(filterByAge, u => u.Age >= minAge && u.Age <= maxAge)
    .WhereIf(filterByRole, u => u.Role == selectedRole);

// 排除空值
var nonEmptyEmails = users.WhereNotNull(u => u.Email);

// 范围过滤
var youngUsers = users.WhereBetween(u => u.Age, 18, 30);

// 集合包含过滤
var vipUsers = users.WhereIn(u => u.UserId, vipIds);
var regularUsers = users.WhereNotIn(u => u.UserId, vipIds);

2. 排序操作示例

// 不区分大小写排序
var sortedUsers = users.OrderByCaseInsensitive(u => u.Name);

// 随机排序（用于随机展示或抽样）
var randomUsers = users.OrderByRandom();

// 自定义优先级排序
var prioritizedTasks = tasks.OrderByPriority(t => {
    if (t.IsUrgent) return 0; // 最高优先级
    if (t.IsImportant) return 1; // 中优先级
    return 2; // 低优先级
});

// 复杂排序（先按优先级，再按截止日期）
var sortedTasks = tasks
    .OrderBy(t => t.Priority)
    .ThenByCaseInsensitive(t => t.Title)
    .ThenBy(t => t.DueDate);

3. 投影操作示例

// 带索引的投影
var indexedUsers = users.SelectWithIndex((user, index) => new {
    Index = index + 1,
    UserName = user.Name,
    DisplayName = $"{index + 1}. {user.Name}"
});

// 条件投影
var userDtos = users.SelectIf(includeDetails, 
    u => new DetailedUserDto { Id = u.Id, Name = u.Name, Details = u.Details },
    u => new BasicUserDto { Id = u.Id, Name = u.Name }
);

// 异常处理投影
var safeValues = data.SelectWithExceptionHandling(
    d => ConvertToTargetType(d),
    defaultValue: defaultTargetValue
);

4. 分组操作示例

// 多级分组
var groupedByDepartmentAndRole = users.GroupByMulti(
    u => u.Department, 
    u => u.Role
);

// 按日期范围分组（按月）
var ordersByMonth = orders.GroupByDateTime(o => o.OrderDate, DateGroupType.Month);

// 按数值范围分组
var usersByAgeGroup = users.GroupByRange(
    u => u.Age, 
    ranges: new[] { 0, 18, 30, 50, 100 }
);

// 不区分大小写分组
var itemsByName = products.GroupByCaseInsensitive(p => p.Category);

5. 树形结构操作示例

// 构建层次结构
var departments = employees
    .Select(e => new { Id = e.Id, Name = e.Name, ManagerId = e.ManagerId })
    .AsHierarchy(e => e.Id, e => e.ManagerId)
    .ToList();

// 扁平化层次结构
var allEmployees = departments.FlattenHierarchy().ToList();

// 深度优先遍历
var depthFirstEmployees = departments.TraverseDepthFirst(d => d.Children).ToList();

// 广度优先遍历
var breadthFirstEmployees = departments.TraverseBreadthFirst(d => d.Children).ToList();

// 查找所有下属
var subordinates = manager.TraverseDepthFirst(m => m.DirectReports).ToList();

// 获取层级信息
var employeesWithLevel = departments
    .TraverseDepthFirst(d => d.Children)
    .Select(e => new {
        Name = e.Name,
        Level = e.Level()
    })
    .ToList();

6. 高级统计计算示例

// 安全统计（处理空集合）
var avgAge = users.AverageOrDefault(u => u.Age, 0);
var totalSalary = users.SumOrDefault(u => u.Salary, 0);

// 高级统计
var medianSalary = employees.Median(e => e.Salary);
var modeDepartment = employees.Mode(e => e.Department);
var percentile90Salary = employees.Percentile(e => e.Salary, 90);
var stdDevAge = employees.StandardDeviation(e => e.Age);

// 滚动统计（用于时间序列分析）
var rollingAverages = dailySales
    .OrderBy(d => d.Date)
    .RollingAverage(d => d.Amount, windowSize: 7); // 7天移动平均

7. 集合操作示例

// 批量处理（避免大数据集内存问题）
var batchResults = largeDataSet
    .Batch(1000) // 每批1000条
    .Select(batch => ProcessBatch(batch))
    .ToList();

// 集合运算
var commonElements = list1.Intersection(list2);
var uniqueElements = list1.UnionDistinct(list2);
var differentElements = list1.Difference(list2);

// 验证包含关系
bool hasAllRequiredRoles = userRoles.ContainsAll(requiredRoles);
bool hasAnyAdminRole = userRoles.ContainsAny(adminRoles);

// 条件集合选择
var resultList = sourceList.IfEmpty(fallbackList);

8. 异步操作示例

// 异步过滤和投影
var activeCustomers = await customers
    .WhereAsync(async c => await IsCustomerActiveAsync(c.Id))
    .SelectAsync(async c => await MapToCustomerDtoAsync(c))
    .ToListAsync();

// 异步集合处理
var processedResults = await items
    .ParallelForEachAsync(async item => {
        return await ProcessItemAsync(item);
    }, maxDegreeOfParallelism: 10);

// 异步聚合
bool allProcessed = await tasks.AllAsync(async t => await IsTaskProcessedAsync(t.Id));
int pendingCount = await tasks.CountAsync(async t => await IsTaskPendingAsync(t.Id));

9. 窗口函数示例

// 滑动窗口（用于时间序列分析）
var weeklyWindows = dailySales
    .OrderBy(d => d.Date)
    .Window(7) // 7天窗口
    .Select(window => new {
        StartDate = window.First().Date,
        EndDate = window.Last().Date,
        TotalSales = window.Sum(d => d.Amount),
        AverageDaily = window.Average(d => d.Amount)
    });

// 滚动统计
var stockAnalysis = stockPrices
    .OrderBy(s => s.Date)
    .RollingAverage(s => s.Price, 20) // 20日均线
    .Zip(
        stockPrices.OrderBy(s => s.Date).RollingAverage(s => s.Price, 50), // 50日均线
        (ma20, ma50) => ma20 > ma50 // 金叉信号
    );

10. 数据转换示例

// 安全类型转换
var stringIds = ids.CastSafe<string>(id => id.ToString());

// 分页列表转换
var pagedProducts = products
    .OrderBy(p => p.Name)
    .ToPagedList(pageNumber: 1, pageSize: 20);

Console.WriteLine($"总页数: {pagedProducts.TotalPages}");
Console.WriteLine($"总记录数: {pagedProducts.TotalCount}");

// 数据格式转换
var jsonData = customers.ToJson();
var csvData = orders.ToCsv();
var dataTable = products.ToDataTable();

使用注意事项

1. 延迟执行特性：

   • 大多数LINQ扩展方法采用延迟执行模式，只在枚举结果时才真正执行
   • 对于多次使用相同查询结果的情况，应使用ToList()、ToArray()等方法立即执行并缓存结果
   • 对于可能产生副作用的操作，要注意延迟执行可能导致的多次执行

2. 性能考虑：

   • 对于大数据集，考虑使用Batch、Chunk等方法分批处理，避免内存溢出
   • 对于频繁使用的查询，使用Cache或Memoize方法缓存结果
   • 尽量在数据源头进行过滤，减少传输和处理的数据量
   • 复杂查询时注意索引的使用和查询优化

3. 异常处理：

   • 使用TryGetValue、CastSafe等安全方法避免异常
   • 对于异步操作，确保正确处理取消和异常情况
   • 对于可能产生空引用的操作，使用WhereNotNull、DefaultIfEmptySafe等方法

4. 数据库查询注意事项：

   • 某些扩展方法可能无法转换为SQL，会导致查询在内存中执行
   • 对于EF Core等ORM，优先使用标准LINQ方法，只在需要时使用扩展方法
   • 使用异步方法时，确保数据库连接支持异步操作

5. 线程安全：

   • 在多线程环境中使用共享集合时，确保正确同步
   • 使用ParallelForEachAsync时注意设置合理的并发度
   • 对于修改集合的操作，注意线程安全问题

6. 避免常见陷阱：

   • 避免在查询表达式中修改外部变量
   • 避免在延迟执行的查询中依赖可变对象
   • 注意闭包变量的生命周期问题
   • 对于非常大的集合，避免使用可能导致多次遍历的操作

7. 测试建议：

   • 对复杂查询进行单元测试，验证结果正确性
   • 测试边界情况（空集合、null值、边界值等）
   • 对性能关键路径进行性能测试
   • 测试异步操作的并发和取消场景

贡献者

• yswenli

许可证

保留所有权利