👁 Image
TJC.Cyclops.Common 2026.6.11.2

Cyclops.Common

🧰 企业级应用开发的瑞士军刀 🧰

Cyclops.Common 是企服版框架中的核心工具类库，提供了丰富的实用功能模块，为框架中的其他组件提供基础支持。该项目集成了大量常用工具类，包括数据处理、加密解密、缓存管理、日志处理、文件操作、HTTP通信等多方面功能，极大地简化了企业级应用的开发工作。

🌟 核心特性

• 数据处理工具：Excel/CSV处理、数据结构与集合操作
• 加密与安全：Base64编码解码、防重放攻击
• 缓存管理：内存缓存、本地缓存
• 事件总线：轻量级事件发布订阅系统
• 错误处理：友好的异常处理机制
• HTTP通信：简化的HTTP客户端、表单上传
• 文件操作：文件读写、路径处理、文件类型判断
• 日志处理：基于log4net的日志记录器
• 时间与日期：日期时间处理、中国农历日历
• 系统工具：反射、动态类型、枚举操作、配置管理
• 网络工具：IP地址处理、IP到地理位置映射
• 图片与二维码：图片处理、二维码生成与识别
• 短信服务：短信发送功能

🛠️ 技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • Encrypt.Library (2025.4.28.1) - 加密库
  • HtmlAgilityPack (1.12.4) - HTML解析
  • log4net (3.2.0) - 日志框架
  • Newtonsoft.Json (13.0.4) - JSON处理
  • NPOI (2.7.5) - Excel处理
  • SharpZipLib (1.4.2) - 压缩解压
  • SkiaSharp (3.119.1) - 图像处理
  • ZXing.Net (0.16.11) - 二维码处理

📦 安装

dotnet add package TJC.Cyclops.Common

🚀 快速开始

Excel文件处理

using Cyclops.Common;

// 读取Excel文件
var dataTable = ExcelUtil.ReadExcelToDataTable("path/to/excel.xlsx");

// 写入Excel文件
ExcelUtil.DataTableToExcel(dataTable, "path/to/output.xlsx");

内存缓存使用

using Cyclops.Common.Cache;

// 创建内存缓存实例
var cache = new MemoryCache();

// 添加缓存项
cache.Set("key", "value", TimeSpan.FromMinutes(10));

// 获取缓存项
if (cache.TryGetValue("key", out string? value))
{
 // 使用缓存值
 Console.WriteLine(value);
}

// 移除缓存项
cache.Remove("key");

HTTP请求发送

using Cyclops.Common.Http;

// 使用HttpClientProxy发送GET请求
var client = new HttpClientProxy();
var result = await client.GetAsync("https://api.example.com/data");

// 发送POST请求
var postData = new { name = "test", value = 123 };
var postResult = await client.PostAsync("https://api.example.com/submit", postData);

📖 使用指南

事件总线使用

using Cyclops.Common.EventBus;
using Cyclops.Common.EventBus.Models;

// 定义事件数据类
public class UserCreatedEvent : BaseEventData
{
 public string UserId { get; set; }
 public string UserName { get; set; }
}

// 配置和初始化事件总线
var bus = BusBuilder.Create()
 .WithConfig(new BusConfig { QueueCapacity = 1000 })
 .Build();

// 订阅事件
bus.Subscribe<UserCreatedEvent>(e =>
{
 Console.WriteLine($"用户创建事件: {e.UserName} (ID: {e.UserId})");
});

// 发布事件
await bus.PublishAsync(new UserCreatedEvent
{
 UserId = "123",
 UserName = "张三"
});

日期时间处理

using Cyclops.Common;

// 格式化日期时间
string formattedDate = DateTimeUtil.ToString(DateTime.Now, "yyyy-MM-dd HH:mm:ss");

// 获取中文星期
string chineseWeekday = DateTimeUtil.GetChineseWeekDay(DateTime.Now);

// 计算两个日期之间的工作日数量
int workDays = DateTimeUtil.GetWorkDays(DateTime.Now, DateTime.Now.AddDays(10));

错误处理

using Cyclops.Common.Errors;

// 抛出友好异常
try
{
 if (someCondition)
 {
 throw new FriendlyException(EnumErrorCode.InvalidParameter, "参数无效");
 }
}
catch (FriendlyException ex)
{
 // 处理友好异常
 Console.WriteLine($"错误码: {ex.ErrorCode}, 错误信息: {ex.Message}");
}

文件操作

using Cyclops.Common.IO;

// 读取文件内容
string content = FileUtil.ReadFileContent("path/to/file.txt");

// 写入文件
FileUtil.WriteFileContent("path/to/output.txt", "Hello, World!");

// 复制文件
FileUtil.CopyFile("source.txt", "destination.txt");

// 检查文件是否存在
bool exists = FileUtil.Exists("path/to/file.txt");

📋 核心功能模块

1. 数据处理工具

• ExcelUtil：Excel文件的读取、写入和格式化
• CsvUtil：CSV文件的解析和生成
• DataTableUtil：DataTable操作的辅助工具
• PagedList：分页列表实现
• ThreadSafeList：线程安全的列表实现
• PagedDictionary：分页字典
• DataSplitter：大数据集合的分割处理

2. 加密与安全

• Base64Util：Base64编码解码
• CalcUtil：计算相关工具方法
• AntiReplayAttacks：防重放攻击功能
• AraReplayAttacksUtil：防重放攻击工具类

3. 缓存管理

• MemoryCache：内存缓存实现
• IServiceCache：服务缓存接口
• LocalCacheUtil：本地缓存工具类

4. 事件总线

• BusBuilder：事件总线构建器
• Publisher：事件发布者
• Subscriber：事件订阅者
• EventQueue：事件队列
• IEventData：事件数据接口

5. HTTP通信

• HttpClientProxy：HTTP客户端代理
• HttpExtension：HTTP扩展方法
• FormUpload：表单上传功能
• FileParameter：文件参数定义

6. 文件操作

• FileUtil：文件操作工具类
• PathUtil：路径处理工具
• FileTypeUtil：文件类型判断工具
• TempFile：临时文件管理

7. 日志处理

• Logger：日志记录器
• LogInfo：日志信息类
• ApiLogInfo：API日志信息类

8. 系统工具

• ReflectionUtil：反射操作工具
• DynamicUtil：动态类型操作工具
• FastILUtil：基于IL的快速反射工具
• EnumUtil：枚举操作工具类
• ConfigUtil：配置文件操作工具
• NacosConfigUtil：Nacos配置中心工具类
• ComputerUtil：计算机系统信息获取工具
• ProcessUtil：进程管理工具

9. 网络工具

• IPUtil：IP地址处理工具
• IPToRegion：IP地址到地理位置的映射
• LANUtil：局域网相关工具

10. 图片与二维码

• ImageUtil：图片处理工具类
• ZXing：二维码生成与识别功能

11. 短信服务

• SmsSender：短信发送服务
• SmsOption：短信服务配置选项

⚠️ 使用注意事项

1. 日志配置：使用Logger前，请确保已正确配置log4net
2. 线程安全：在多线程环境下使用集合类时，优先选择ThreadSafeList等线程安全实现
3. 资源释放：使用文件操作和流操作时，请确保正确释放资源，避免资源泄漏
4. 异常处理：在生产环境中，建议使用FriendlyException进行异常处理，提供友好的错误提示
5. 缓存管理：使用缓存时，注意设置合理的过期时间，避免内存占用过大
6. 配置管理：对于需要频繁变更的配置，建议使用NacosConfigUtil从配置中心读取
7. 性能考虑：对于性能敏感的操作，可以使用FastILUtil等高性能工具类
8. 版本兼容性：使用第三方库时，注意版本兼容性问题，特别是Newtonsoft.Json等常用库

🤝 贡献

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

📄 许可证

MIT License

Cyclops.Common - 为企业级应用开发提供强大的工具支持，让开发变得更简单！✨