# WpfAdmin.Hutool

**Repository Path**: wpfadmin/wa.hutool

## Basic Information

- **Project Name**: WpfAdmin.Hutool
- **Description**: No description available
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2025-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目介绍

Java 版项目地址: <https://github.com/chinabugotech/hutool>

## 🎯 项目目标
基于 .NET 10 构建的现代化工具库，提供高性能、易用的工具类和方法，简化日常开发工作。

## 📋 开发计划

### 🏗️ 第一阶段：核心基础模块 ⭐⭐⭐⭐⭐ (优先级：最高)
**目标**：建立项目基础，提供最常用的工具类
**预计时间**：4-6 周
**依赖关系**：无

### 1. Core模块 (Hutool.NET.Core)

#### 字符串工具 (StringUtil)
- [x] **判空检查**
  - *实现：利用`string.IsNullOrEmpty`和`string.IsNullOrWhiteSpace`*
  - *扩展：提供`string.IsEmpty()`、`string.IsNotEmpty()`扩展方法*
  - *性能：使用`ReadOnlySpan<char>`优化内存分配*
- [x] **字符串格式化**
  - *实现：结合`string.Format`和插值表达式（.NET 10 原生支持）*
  - *功能：支持命名参数格式化和模板缓存*
  - *性能：使用`StringBuilder`和`StringBuilder.AppendFormat`*
- [x] **字符串截取和拼接**
  - *实现：使用`StringBuilder`和`ReadOnlySpan<char>`优化性能*
  - *API：提供链式调用和流式API*
  - *功能：支持安全截取（防止越界）*
- [x] **大小写转换**
  - *实现：考虑文化敏感性`CultureInfo.InvariantCulture`*
  - *扩展：添加`ToTitleCase`、`ToCamelCase`等扩展方法*
  - *性能：使用`Span<char>`避免字符串分配*
- [x] **字符串比较**
  - *实现：提供`StringComparison`选项和模糊匹配*
  - *功能：支持正则表达式和模式匹配*
  - *性能：使用`ReadOnlySpan<char>`进行高效比较*
- [x] **编码转换**
  - *实现：使用`Encoding`类和`System.Text`命名空间*
  - *功能：处理BOM标记和编码检测*
  - *性能：使用`Span<byte>`和`Memory<byte>`优化*

#### 日期时间工具 (DateTimeUtil)
- [x] **日期格式化**
  - *实现：使用`DateTime.ToString(format, CultureInfo)`和`DateOnly`/`TimeOnly`*
  - *功能：支持自定义格式模板和本地化*
  - *性能：缓存格式化器避免重复创建*
- [x] **日期解析**
  - *实现：使用`DateTime.TryParseExact`和`DateOnly.TryParse`*
  - *功能：支持多种日期格式自动识别和容错处理*
  - *扩展：提供`TryParse`扩展方法*
- [x] **日期计算**
  - *实现：使用`TimeSpan`和`DateOnly`进行日期运算*
  - *功能：考虑闰年、月末等边界情况*
  - *扩展：提供工作日计算、节假日判断等*
- [x] **时区转换**
  - *实现：使用`TimeZoneInfo`和`TimeZoneInfo.ConvertTime`*
  - *功能：处理夏令时变化和时区偏移*
  - *扩展：支持`DateTimeOffset`和`TimeOnly`时区转换*
- [x] **日期比较**
  - *实现：提供精确到秒/毫秒的比较选项*
  - *功能：支持日期范围判断和相对时间计算*
  - *扩展：提供`IsBetween`、`IsToday`等便捷方法*

```csharp
// 日期时间格式化与解析示例
var dt = new DateTime(2024, 12, 31, 23, 59, 59);
var s1 = WpfAdmin.Hutool.Core.DateTimeUtil.Format(dt); // 2024-12-31 23:59:59
var ok = WpfAdmin.Hutool.Core.DateTimeUtil.TryParseDateTime("2024-12-31 23:59:59", out var parsed);

// 日期计算
var days = WpfAdmin.Hutool.Core.DateTimeUtil.DiffDays(DateTime.Now, DateTime.Now.AddDays(3)); // 3
var eom = WpfAdmin.Hutool.Core.DateTimeUtil.EndOfMonth(new DateOnly(2024, 2, 1)); // 2024-02-29

// 时区转换
var utc = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
var beijing = WpfAdmin.Hutool.Core.DateTimeUtil.ConvertFromUtc(utc, "China Standard Time");

// 比较与范围
var eqSec = WpfAdmin.Hutool.Core.DateTimeUtil.Equals(dt, dt.AddMilliseconds(500), "Seconds"); // true
var between = WpfAdmin.Hutool.Core.DateTimeUtil.IsBetween(dt, dt.AddHours(-1), dt.AddHours(1)); // true
```

#### 数字工具 (NumericUtil)
- [x] **数字格式化**
  - *注意：使用`NumberFormatInfo`处理区域设置*
  - *注意：支持货币、百分比等格式*
- [x] **精度计算**
  - *注意：使用`decimal`类型避免浮点数精度问题*
  - *注意：提供舍入模式选择*
- [x] **类型转换**
  - *注意：使用`Convert.ChangeType`和泛型约束*
  - *注意：提供安全转换（TryParse模式）*
- [x] **数学运算增强**
  - *注意：扩展`Math`类功能*
  - *注意：处理溢出异常*

```csharp
// 数字格式化与解析示例
var s1 = WpfAdmin.Hutool.Core.NumericUtil.Format(1234.56m, "N2"); // 1,234.56
var money = WpfAdmin.Hutool.Core.NumericUtil.FormatCurrency(12.3m, 2); // ￥12.30（根据文化）
var percent = WpfAdmin.Hutool.Core.NumericUtil.FormatPercent(0.123m, 1); // 12.3 %

// 解析
var ok = WpfAdmin.Hutool.Core.NumericUtil.TryParseDecimal("1,234.56", out var d1);

// 精度与舍入
var r = WpfAdmin.Hutool.Core.NumericUtil.Round(1.25m, 1); // 1.2 (ToEven)
var eq = WpfAdmin.Hutool.Core.NumericUtil.Equals(1.2345m, 1.2344m, 3); // true

// 类型转换与数学
var can = WpfAdmin.Hutool.Core.NumericUtil.TryToDecimal("456.78", out var d2); // true
var clamped = WpfAdmin.Hutool.Core.NumericUtil.Clamp(12m, 5m, 10m); // 10
var pct = WpfAdmin.Hutool.Core.NumericUtil.Percent(1m, 4m, 2); // 0.25
```

#### 集合工具 (CollectionUtil)
- [x] **List操作增强**
  - *注意：利用LINQ扩展方法*
  - *注意：提供线程安全选项*
- [x] **Dictionary操作增强**
  - *注意：使用`TryGetValue`模式*
  - *注意：支持深度合并*
- [x] **集合转换**
  - *注意：使用泛型和`IEnumerable<T>`*
  - *注意：提供延迟执行选项*
- [x] **集合比较**
  - *注意：实现`IEqualityComparer<T>`*
  - *注意：支持深度比较*

#### 对象工具 (ObjectUtil)
- [x] **属性复制**
  - *注意：使用反射`PropertyInfo`和表达式树优化性能*
  - *注意：支持浅复制和深复制*
- [x] **反射操作**
  - *注意：缓存`Type`信息提升性能*
  - *注意：处理泛型类型和可空类型*
- [x] **对象比较**
  - *注意：实现`IComparable<T>`接口*
  - *注意：支持自定义比较规则*

#### 类型转换 (TypeConverter)
- [x] **基础类型转换**
  - *注意：使用`TypeConverter`类和`Convert`类*
  - *注意：支持可空类型转换*
- [x] **复杂对象转换**
  - *注意：使用反射和表达式树*
  - *注意：提供类型映射配置*

```csharp
// 集合工具示例
var list = new List<string> { "a", "aa", "b" };
var distinct = WpfAdmin.Hutool.Core.CollectionUtil.DistinctBy(list, s => s[0]);

// 对象工具示例（使用具体类型）
public class UserDto { public int Id { get; set; } public string? Name { get; set; } }
public class UserModel { public int Id { get; set; } public string? Name { get; set; } }
var src = new UserDto { Id = 1, Name = "Tom" };
var dest = new UserModel();
WpfAdmin.Hutool.Core.ObjectUtil.CopyProperties(src, dest);

// 类型转换示例
var ok = WpfAdmin.Hutool.Core.TypeConverterUtil.TryConvert<int>("42", out var num); // true
// 复杂对象转换示例
var dto = new PersonDto { Name = "Tom", Age = 20 };
var converted = WpfAdmin.Hutool.Core.TypeConverterUtil.TryConvertObject<PersonModel>(dto, out var model);
```

### 2. IO模块 (Hutool.NET.IO)

#### 文件工具 (FileHelper)
- [ ] **文件读写**
  - *注意：使用`using`语句确保资源释放*
  - *注意：支持异步操作`async/await`*
- [ ] **文件操作**
  - *注意：使用`Path.Combine`构建路径*
  - *注意：处理文件锁定和权限问题*
- [ ] **目录操作**
  - *注意：使用`DirectoryInfo`和`FileInfo`*
  - *注意：支持递归操作和模式匹配*
- [ ] **文件监控**
  - *注意：使用`FileSystemWatcher`*
  - *注意：处理事件重复触发*

#### 流工具 (StreamHelper)
- [x] **流复制**
  - *实现：使用 `ArrayPool<byte>` 缓冲区，支持进度回调*
  - *新增：限速支持（块延迟 + 令牌桶平滑限速）*
  - *新增：断点续传接口 `ResumeCopyAsync`*
- [x] **流转换**
  - *实现：内存流/字节转换零拷贝优化（优先使用 `TryGetBuffer`）*

```csharp
// 令牌桶限速复制
var bucket = new WpfAdmin.Hutool.Core.TokenBucket(capacityBytes: 8 * 1024, bytesPerSecond: 8 * 1024);
await WpfAdmin.Hutool.Core.StreamUtil.CopyWithTokenBucketAsync(src, dst, bucket, progress: (done, total) => { /* ... */ });
```

## 第二阶段：常用功能模块 ⭐⭐⭐⭐

### 3. JSON模块 (Hutool.NET.Json)

#### JSON序列化
- [x] **对象序列化/解析（System.Text.Json）**
  - *新增：Source Generator 友好接口（零反射）*
  - *新增：策略化选项 `CreateOptions`（忽略默认值/空值、日期格式、枚举字符串、循环引用）*

```csharp
var options = WpfAdmin.Hutool.Core.JsonUtil.CreateOptions(
    enumAsString: true,
    dateTimeFormat: "yyyy-MM-dd HH:mm:ss",
    preserveReferences: true);
var json = WpfAdmin.Hutool.Core.JsonUtil.Serialize(obj, options);
```

### 4. HTTP模块 (Hutool.NET.Http)

#### HTTP客户端
- [x] **GET/POST请求**：支持超时、重试（白/黑名单、指数退避、抖动）
- [x] **请求参数处理**：表单 `PostFormAsync`、多部分 `PostMultipartAsync`
- [x] **响应处理**：`DownloadToStreamAsync` 流式下载，结合 `StreamUtil` 进度回调
- [x] **认证/代理**：`SetBearerToken`、`SetDefaultHeader`、`SetProxy`

```csharp
// 带超时与重试的 GET
var content = await WpfAdmin.Hutool.Core.HttpUtil.GetStringAsync(
    "https://api.example.com",
    timeout: TimeSpan.FromSeconds(5),
    retryCount: 3);

// 多部分上传
var result = await WpfAdmin.Hutool.Core.HttpUtil.PostMultipartAsync("https://upload", multi =>
{
    multi.Add(new StringContent("abc"), "name");
    multi.Add(new ByteArrayContent(fileBytes), "file", "a.bin");
});
```

### 5. 加密模块 (Hutool.NET.Crypto)

#### 哈希算法
- [ ] **MD5/SHA系列**
  - *注意：使用`System.Security.Cryptography`*
  - *注意：支持文件哈希计算*
- [ ] **HMAC算法**
  - *注意：实现密钥哈希*
  - *注意：支持多种哈希算法*

#### 对称加密
- [ ] **AES加密**
  - *注意：使用`AesManaged`类*
  - *注意：支持多种填充模式*
- [ ] **DES/3DES加密**
  - *注意：处理密钥长度限制*
  - *注意：提供向量初始化*

#### 非对称加密
- [ ] **RSA加密**
  - *注意：使用`RSACryptoServiceProvider`*
  - *注意：支持密钥对生成和导入*

### 6. 配置模块 (Hutool.NET.Setting)

#### 配置文件处理
- [ ] **Properties文件解析**
  - *注意：兼容Java Properties格式*
  - *注意：支持Unicode转义*
- [ ] **配置读取增强**
  - *注意：扩展`ConfigurationManager`*
  - *注意：支持配置热重载*
- [ ] **环境变量处理**
  - *注意：使用`Environment.GetEnvironmentVariable`*
  - *注意：支持配置优先级*

## 第三阶段：扩展功能模块 ⭐⭐⭐

### 7. 缓存模块 (Hutool.NET.Cache)

#### 内存缓存
- [ ] **LRU缓存实现**
  - *注意：使用`Dictionary`和`LinkedList`组合*
  - *注意：实现线程安全*
- [ ] **过期策略**
  - *注意：使用`Timer`实现定期清理*
  - *注意：支持滑动过期和绝对过期*
- [ ] **缓存统计**
  - *注意：提供命中率等统计信息*
  - *注意：支持缓存监控*

### 8. 定时任务模块 (Hutool.NET.Cron)

#### Cron表达式
- [ ] **表达式解析**
  - *注意：实现标准Cron格式解析*
  - *注意：支持秒级精度*
- [ ] **任务调度**
  - *注意：基于`Timer`和`Task`*
  - *注意：支持任务并发控制*
- [ ] **任务管理**
  - *注意：提供任务启停控制*
  - *注意：支持任务状态监控*

## 第四阶段：高级功能模块 ⭐⭐

### 11. Excel模块 (Hutool.NET.Excel)

#### Excel操作
- [ ] **Excel读取**
  - *注意：兼容xls和xlsx格式*
  - *注意：使用第三方库或COM组件*
- [ ] **Excel写入**
  - *注意：支持样式和格式设置*
  - *注意：处理大数据量内存优化*
- [ ] **数据转换**
  - *注意：支持对象与Excel行转换*
  - *注意：提供数据验证*

### 12. 数据库模块 (Hutool.NET.Db)

#### 数据库操作
- [ ] **连接管理**
  - *注意：使用连接池优化*
  - *注意：支持事务操作*
- [ ] **SQL构建**
  - *注意：提供类型安全的SQL构建器*
  - *注意：防止SQL注入*
- [ ] **ORM简化**
  - *注意：实现简单的对象映射*
  - *注意：支持LINQ查询*

### 13. JWT模块 (Hutool.NET.Jwt)

#### JWT处理
- [ ] **令牌生成**
  - *注意：支持多种签名算法*
  - *注意：处理过期时间*
- [ ] **令牌验证**
  - *注意：验证签名和有效期*
  - *注意：支持自定义声明*

### 🔧 第二阶段：现代化功能模块 ⭐⭐⭐⭐ (优先级：高)
**目标**：提供现代 .NET 开发必需的功能
**预计时间**：6-8 周
**依赖关系**：依赖第一阶段 Core 模块

### 14. 依赖注入模块 (Hutool.NET.DI)
- [ ] **服务注册增强**
  - *实现：基于`Microsoft.Extensions.DependencyInjection`*
  - *功能：提供装饰器模式、条件注册等高级功能*
  - *性能：使用源生成器优化注册性能*
- [ ] **生命周期管理**
  - *实现：支持单例、作用域、瞬态等生命周期*
  - *功能：提供自定义生命周期管理*
- [ ] **服务发现**
  - *实现：自动发现和注册服务*
  - *功能：支持特性标记和约定注册*

### 15. 配置管理模块 (Hutool.NET.Configuration)
- [ ] **配置绑定**
  - *实现：基于`Microsoft.Extensions.Configuration`*
  - *功能：支持强类型配置绑定和验证*
  - *性能：使用源生成器优化绑定性能*
- [ ] **配置热重载**
  - *实现：支持配置文件变更自动重载*
  - *功能：提供配置变更通知机制*
- [ ] **环境配置**
  - *实现：支持多环境配置管理*
  - *功能：提供配置优先级和覆盖机制*

### 16. 健康检查模块 (Hutool.NET.Health)
- [ ] **健康检查**
  - *实现：基于`Microsoft.Extensions.Diagnostics.HealthChecks`*
  - *功能：提供数据库、HTTP、自定义健康检查*
  - *监控：支持健康检查结果聚合和报告*
- [ ] **指标收集**
  - *实现：集成`System.Diagnostics.Metrics`*
  - *功能：提供性能指标和业务指标收集*

### 17. 并发工具模块 (Hutool.NET.Concurrency)
- [ ] **异步工具**
  - *实现：基于`Task`和`ValueTask`*
  - *功能：提供超时控制、取消令牌、重试机制*
  - *性能：使用`ConfigureAwait(false)`优化性能*
- [ ] **并行处理**
  - *实现：基于`Parallel`和`PLINQ`*
  - *功能：提供数据并行和任务并行工具*
- [ ] **同步原语**
  - *实现：基于`SemaphoreSlim`、`AsyncLock`等*
  - *功能：提供异步同步原语和锁管理*

### 18. 序列化模块 (Hutool.NET.Serialization)
- [ ] **JSON序列化**
  - *实现：基于`System.Text.Json`（.NET 10 原生）*
  - *功能：支持自定义序列化器、循环引用处理*
  - *性能：使用源生成器优化序列化性能*
- [ ] **XML序列化**
  - *实现：基于`System.Xml`和`System.Xml.Linq`*
  - *功能：支持LINQ to XML和XPath查询*
- [ ] **二进制序列化**
  - *实现：基于`System.Runtime.Serialization`*
  - *功能：支持自定义序列化器和版本兼容性*

## 🚀 第三阶段：高级功能模块 ⭐⭐⭐ (优先级：中)
**目标**：提供专业级功能和企业级特性
**预计时间**：8-10 周
**依赖关系**：依赖前两个阶段

### 19. 缓存模块 (Hutool.NET.Cache)

#### 内存缓存
- [ ] **内存缓存**
  - *实现：基于`Microsoft.Extensions.Caching.Memory`*
  - *功能：支持LRU、LFU等淘汰策略*
  - *性能：使用`ConcurrentDictionary`和`MemoryCache`*
- [ ] **分布式缓存**
  - *实现：支持Redis、SQL Server等*
  - *功能：提供缓存同步和一致性保证*
- [ ] **缓存统计**
  - *实现：提供命中率、性能统计*
  - *监控：支持缓存监控和告警*

### 20. 消息队列模块 (Hutool.NET.Messaging)

#### 消息发布订阅
- [ ] **消息发布订阅**
  - *实现：基于`Microsoft.Extensions.Messaging`*
  - *功能：支持内存和分布式消息队列*
- [ ] **事件总线**
  - *实现：提供进程内和跨进程事件总线*
  - *功能：支持事件过滤、路由、重试*

### 21. 工作流模块 (Hutool.NET.Workflow)

#### 状态机
- [ ] **状态机**
  - *实现：提供轻量级状态机实现*
  - *功能：支持状态转换、条件判断、动作执行*
- [ ] **工作流引擎**
  - *实现：基于有向无环图(DAG)的工作流*
  - *功能：支持并行执行、错误处理、重试机制*

### 🎯 第四阶段：专业功能模块 ⭐⭐ (优先级：低)
**目标**：提供特定领域的专业功能
**预计时间**：10-12 周
**依赖关系**：依赖前三个阶段

### 22. 机器学习模块 (Hutool.NET.ML)

#### 基础算法
- [ ] **基础算法**
  - *实现：提供常用机器学习算法*
  - *功能：支持分类、回归、聚类等*
- [ ] **数据处理**
  - *实现：提供数据预处理和特征工程工具*
  - *功能：支持数据清洗、归一化、特征选择*

### 23. 图像处理模块 (Hutool.NET.Image)

#### 图像操作
- [ ] **图像操作**
  - *实现：基于`System.Drawing`和`SkiaSharp`*
  - *功能：支持缩放、裁剪、滤镜、水印*
- [ ] **格式转换**
  - *实现：支持多种图像格式互转*
  - *功能：提供批量处理和优化*

## 📊 开发进度跟踪

### 里程碑计划
- **M1** (4周)：完成核心基础模块
- **M2** (8周)：完成现代化功能模块
- **M3** (12周)：完成高级功能模块
- **M4** (16周)：完成专业功能模块

### 质量保证
- **单元测试覆盖率**：≥ 90%
- **性能基准测试**：每个模块提供性能基准
- **文档完整性**：API文档和示例代码
- **代码质量**：遵循 .NET 编码规范

## 🔧 技术栈

### 核心框架
- **.NET 10**：目标框架
- **C# 12**：编程语言
- **Source Generators**：代码生成优化

### 主要依赖
- **Microsoft.Extensions.***：微软官方扩展库
- **System.Text.Json**：JSON序列化
- **System.Diagnostics.Metrics**：指标收集
- **System.Threading.Channels**：异步通信

## 📝 备注

### 开发原则
1. **性能优先**：充分利用 .NET 10 的性能特性
2. **内存友好**：使用`Span<T>`、`Memory<T>`等零分配技术
3. **异步优先**：所有IO操作都提供异步版本
4. **可扩展性**：提供插件机制和扩展点
5. **向后兼容**：保持API的向后兼容性

### 贡献指南
1. 遵循 .NET 编码规范
2. 提供完整的单元测试
3. 更新相关文档
4. 通过所有CI检查