TJC.Cyclops.Linq 2026.5.11.1

Cyclops.Linq

🔍 强大的LINQ扩展库 🔍

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

🌟 核心特性

• 丰富的集合操作：提供大量扩展方法，简化集合的过滤、排序、投影等操作
• 查询优化：支持批量处理、延迟执行增强、缓存等性能优化功能
• 高级统计计算：支持平均值、中位数、标准差等高级统计功能
• 树形结构支持：提供树形结构的创建、遍历和操作功能
• 异步操作：支持异步LINQ操作，提高应用性能
• 安全操作：提供安全的类型转换、空值处理等功能
• 窗口函数：支持滑动窗口、滚动统计等高级数据处理
• 数据转换：支持多种格式的数据转换，如JSON、CSV、DataTable等
• 条件操作：提供丰富的条件判断和分支处理功能
• 并行处理：支持并行遍历和处理集合数据

🛠️ 技术栈

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

📦 安装

dotnet add package TJC.Cyclops.Linq

🚀 快速开始

基本使用

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

using Cyclops.Linq;

条件过滤示例

using Cyclops.Linq;

// 基本条件过滤
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);

排序操作示例

using Cyclops.Linq;

// 不区分大小写排序
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);

📖 使用指南

投影操作示例

using Cyclops.Linq;

// 带索引的投影
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
);

分组操作示例

using Cyclops.Linq;

// 多级分组
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);

树形结构操作示例

using Cyclops.Linq;

// 构建层次结构
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();

高级统计计算示例

using Cyclops.Linq;

// 安全统计（处理空集合）
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天移动平均

集合操作示例

using Cyclops.Linq;

// 批量处理（避免大数据集内存问题）
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);

异步操作示例

using Cyclops.Linq;

// 异步过滤和投影
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));

🔧 核心功能模块

1. 集合操作扩展

• 过滤操作：WhereIf、WhereNot、WhereNotNull、WhereNotEmpty、WhereBetween、WhereIn、WhereNotIn
• 排序操作：OrderByCaseInsensitive、OrderByRandom、OrderByPriority、OrderByCustom、ThenByCaseInsensitive
• 投影操作：SelectWithIndex、SelectIf、SelectManyWithIndex、SelectDistinct、SelectWithExceptionHandling

2. 查询优化

• 性能优化：Batch、Chunk、TakeUntil、SkipUntil、FirstOrDefaultAsync、SingleOrDefaultAsync、AnyAsync、CountAsync
• 延迟执行增强：Materialize、Cache、Memoize、Defer、EvaluateWhen

3. 聚合操作

• 统计计算：AverageOrDefault、SumOrDefault、MaxOrDefault、MinOrDefault、Median、Mode、Percentile、StandardDeviation、Variance
• 集合操作：Merge、ZipMany、Interleave、Difference、Intersection、UnionDistinct、SymmetricDifference、ContainsAll、ContainsAny

4. 特殊数据结构支持

• 树形结构：AsHierarchy、FlattenHierarchy、TraverseDepthFirst、TraverseBreadthFirst、FindDescendants、FindAncestors、Level
• 分组操作：GroupByMulti、GroupByRange、GroupByDateTime、GroupByKeySelector、GroupByCaseInsensitive、GroupByEqualityComparer

5. 数据转换

• 类型转换：OfTypeOrEmpty、CastSafe、ConvertAll、ToDictionarySafe、ToLookupSafe
• 集合转换：ToPagedList、ToDataTable、ToJson、ToCsv、ToXml、ToObservableCollection

6. 特殊操作

• 条件操作：IfEmpty、IfSingle、IfMultiple、ElseIf、ThenByCondition
• 循环和索引：ForEachIndex、ForEachParallel、ForEachWithTimeout、ForEachUntil、TakeLast、SkipLast、FirstIndexOf、LastIndexOf

7. 高级查询

• 窗口函数：Window、RollingAverage、RollingSum、RollingMax、RollingMin
• 集合分区：PartitionBy、Split、SplitWhen、SplitIntoChunks、ChunkBy

8. 异步操作

• 异步LINQ：WhereAsync、SelectAsync、OrderByAsync、GroupByAsync、AnyAsync、AllAsync、CountAsync、SumAsync、AverageAsync
• 异步集合操作：ToListAsync、ToArrayAsync、ToDictionaryAsync、ForEachAsync、ParallelForEachAsync、WhenAllAsync

9. 安全操作

• 安全操作：FirstOrEmpty、LastOrEmpty、ElementAtOrEmpty、SingleOrEmpty、DefaultIfEmptySafe、TryGetValue
• 验证操作：IsEmptyOrNull、IsNullOrEmpty、IsSingle、IsMultiple、HasDuplicates、IsSorted、IsDistinct、AllNotNull、AllNotDefault、AnyNotNull、AnyNotDefault

⚠️ 使用注意事项

1. 延迟执行特性：

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

2. 性能考虑：

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

3. 异常处理：

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

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

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

5. 线程安全：

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

6. 避免常见陷阱：

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

🤝 贡献

我们欢迎社区贡献！如果您有任何想法或建议，欢迎提交 Issue 或 Pull Request。

📄 许可证

MIT License

Cyclops.Linq - 让数据查询和处理变得简单高效，为企业应用提供强大的LINQ增强能力！✨