BugFree.Core 1.2.2026.614-beta1516

BugFree.Core

📖 项目介绍

BugFree.Core 是一个功能强大的 .NET 工具类库，旨在为开发人员提供高效、可靠的常用工具和扩展方法。该库包含了编解码、枚举处理、集合操作、IP地址转换、路径安全防护、单位格式化等实用功能，同时还提供了安全随机字符串生成和系统资源压力测试等高级工具。

核心特性

• 全面覆盖：涵盖开发中常用的各种工具类和扩展方法
• 跨平台支持：支持 Windows、Linux、macOS 等多种操作系统
• 高性能：所有实现都经过优化，确保高性能和低内存占用
• 易用性：提供简洁的API设计，易于集成和使用
• 安全性：包含路径安全防护、安全随机字符串生成等安全相关功能

🎯 功能特性

扩展方法（Extensions）

特性（Attributes）

工具类（Tools）

🎮 资源压力测试（ResourceStressController）

概述

ResourceStressController 是一个系统资源压力测试工具，用于模拟服务器高负载场景。它可以动态调节CPU、内存、磁盘的使用率，支持闭环反馈控制，确保系统资源使用率稳定在目标值附近。

主要用途：

• 向客户展示服务器硬件性能
• 进行压力测试和性能评估
• 模拟高负载场景下的系统行为
• 验证系统在资源紧张时的稳定性

架构设计

Tools/ResourceStress/
├── ResourceStressController.cs    # 统一入口，编排所有生成器
├── ResourceStressOptions.cs       # 配置类型
├── ResourceStressSnapshot.cs      # 状态快照
├── CpuStressGenerator.cs          # CPU 压力（满转线程 + 小数 PWM）
├── MemoryStressGenerator.cs       # 内存压力（字节数组块）
├── DiskStressGenerator.cs         # 磁盘压力（文件创建/删除）
└── Platform/
    ├── ISystemMonitor.cs          # 跨平台系统监控抽象
    └── SystemMonitorFactory.cs    # 工厂 + Win/Linux/macOS 实现

跨平台支持

控制算法

三种资源使用同一套控制策略：

flowchart LR
    A[系统监控\n实时 CPU/内存/磁盘] --> B[EMA 指数平滑\n消除尖峰噪声]
    B --> C{安全检查\n超上限?}
    C -->|是| D[熔断: 释放全部]
    C -->|否| E[闭环缺口填充\ngap/perUnit × Damping]
    E --> F[调整负载单元\n线程/内存块/文件]
    F --> A
    D --> A

控制策略说明：

1. EMA指数平滑：使用指数移动平均算法消除系统监控数据的尖峰噪声
2. 安全检查：当资源使用率超过安全上限时，立即释放所有资源进行熔断保护
3. 闭环缺口填充：根据目标使用率与当前使用率的差值，动态调整资源负载
4. 自适应调节：支持滞后恢复，防止在安全边界频繁切换状态

使用示例

using BugFree.Core.Tools.ResourceStress;

// 创建控制器实例
var ctrl = new ResourceStressController(new ResourceStressOptions
{
    Cpu    = new() { TargetUsagePercent = 80,  SafetyUpperPercent = 95 },
    Memory = new() { TargetUsagePercent = 70,  SafetyUpperPercent = 95 },
    Disk   = new() { TargetUsagePercent = 60,  SafetyUpperPercent = 90 },
});

// 订阅状态变化回调
ctrl.OnStatusChanged = s =>
{
    string direction = s.CurrentPercent < s.TargetPercent ? "加压" : "释压";
    Console.WriteLine($"[{s.ResourceType}] {s.CurrentPercent:F1}% / 目标 {s.TargetPercent}% | {direction}");
};

ctrl.Start();        // 开始施加压力
// ... 保持运行 ...
ctrl.Stop();         // 停止压力测试
ctrl.Dispose();      // 释放资源

配置说明

Demo 控制台

项目附带交互式控制台 Demo，支持5种压力测试模式：

dotnet run --project BugFree.Core.Demo

支持模式：

• CPU压力测试
• 内存压力测试
• 磁盘压力测试
• 全资源压力测试
• 自定义参数压力测试

Demo 提供可视化进度条和实时状态显示，方便监控压力测试过程。

🚀 快速开始

安装

通过 NuGet 安装：

dotnet add package BugFree.Core

或者通过包管理器控制台：

Install-Package BugFree.Core

使用示例

// 1. 编解码
using BugFree.Core.Extensions;

byte[] data = "Hello World".GetBytes();
string hex = data.ToHex();              // "48656c6c6f20576f726c64"
string base64 = data.ToBase64();        // "SGVsbG8gV29ybGQ="
string base64Url = data.ToBase64(urlSafe: true); // URL 安全模式
string base62 = data.ToBase62();        // 短 ID 友好编码
if (base62.TryToBase62(out var decoded)) { } // Try 安全解码

// 2. 枚举描述
enum Status { [Description("正常")] Active, [Description("已禁用")] Disabled }
string desc = Status.Active.GetDescription(); // "正常"

// 3. 单位格式化
long fileSize = 2_147_483_648;
string formatted = fileSize.UnitFormatSize(UnitFormatExtensions.UnitKind.Storage);
// 输出: "2.00 GB"

// 4. 路径安全
string safePath = PathSecurityHelper.NormalizePart("user/avatar.png");
// 拒绝 "../etc/passwd" 等路径穿越输入

// 5. 随机字符串
var options = new RandomStringOptions
{
    Length = 8,
    Kind = RandomStringKind.Alphanumeric,
    ExcludeConfusingCharacters = true
};
string code = SecureRandomStringGenerator.Generate(options);

// 6. IP 地址转换
if ("192.168.1.1".TryToIpUInt32(out uint ipValue)) { }
var (network, mask) = "10.0.0.0/24".ToCidrNetwork();

// 7. 集合操作
new[] { 1, 2, 3 }.ForEach(x => Console.WriteLine(x));
list.AddRange(otherItems);

// 8. 特性获取
typeof(MyEnum).GetFieldAttribute<DescriptionAttribute>("FieldName");

📦 项目结构

BugFree.Core/
├── Attributes/          # 自定义特性
│   └── DisplayAttribute.cs
├── Extensions/          # 扩展方法
│   ├── AttributeExtensions.cs     # 字段特性扩展
│   ├── CodecExtensions.cs         # 编解码扩展
│   ├── CollectionExtensions.cs    # 集合扩展
│   ├── DictionaryExtensions.cs    # 字典扩展
│   ├── EnumExtensions.cs         # 枚举扩展
│   ├── IpConvertExtensions.cs    # IP 地址转换
│   ├── PathSecurityHelper.cs     # 路径安全防护
│   ├── TcpClientExtensions.cs    # TCP 连接检测
│   └── UnitFormatExtensions.cs   # 单位格式化
└── Tools/               # 工具类
    ├── ResourceStressController.cs    # 资源压力测试
    └── SecureRandomStringGenerator.cs # 安全随机字符串

🛠️ 技术要求

• .NET 8.0 / .NET 10.0
• C# 最新语言版本
• 支持 Windows / Linux 跨平台

🤝 参与贡献

1. Fork 本仓库
2. 新建特性分支 (git checkout -b feature/xxx)
3. 提交代码 (git commit -m '添加xxx功能')
4. 推送到分支 (git push origin feature/xxx)
5. 新建 Pull Request

📄 开源协议

本项目基于 MIT 协议开源，详见 LICENSE 文件。

📮 联系我们

• 作者：IoTHub开发团队
• Gitee：https://gitee.com/BugFree_1/BugFree.Core