BugFree.Core 1.2.2026.703-beta1428

BugFree.Core

📖 项目介绍

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

核心特性

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

🎯 功能特性

扩展方法（Extensions）

特性（Attributes）

工具类（Tools）

🧵 线程池监控（ThreadPoolMonitor）

概述

ThreadPoolMonitor 用于在业务进程内定时采集 .NET 线程池指标，并根据阈值输出健康状态和告警。它适合接入日志、Prometheus、OpenTelemetry 或其它监控平台，也可用于线上问题排查前的基础埋点。

核心指标：

• Worker / IO 线程：最小值、最大值、可用数、活跃数、使用率
• 排队任务：ThreadPool.PendingWorkItemCount
• 完成任务：ThreadPool.CompletedWorkItemCount、采样窗口增量与每秒完成速率
• 未观测异常：TaskScheduler.UnobservedTaskException
• 诊断建议：根据 Pending、Worker、IO、未观测异常输出可能原因和处置动作

使用示例

using BugFree.Core.Tools.ThreadPoolMonitoring;

using var monitor = new ThreadPoolMonitor(new ThreadPoolMonitorOptions
{
    SampleIntervalMs = 5000,
    PendingWorkItemWarningThreshold = 50,
    PendingWorkItemCriticalThreshold = 100,
});

monitor.OnMetricChanged = s =>
{
    Console.WriteLine(
        $"待处理 Pending={s.PendingWorkItemCount}, " +
        $"工作线程 Worker={s.ActiveWorkerThreads}/{s.MaxWorkerThreads}, " +
        $"速率 Rate={s.CompletedWorkItemRatePerSecond:F2}/s");
};

monitor.OnAlert = alert =>
{
    Console.WriteLine($"告警 Alert [{alert.Health.Level}] {alert.Health.Message}");
    Console.WriteLine($"可能原因 Probable cause：{alert.Advice.ProbableCause}");
    Console.WriteLine($"建议动作 Recommended action：{alert.Advice.RecommendedAction}");
    Console.WriteLine($"排查命令 Diagnostic command：{alert.Advice.DiagnosticCommand}");
};

monitor.Start();

也可以直接使用内置默认配置：

using var monitor = new ThreadPoolMonitor(ThreadPoolMonitorOptions.CreateProductionDefaults());

阈值如何设置

ThreadPoolMonitorOptions 的默认值只适合作为起步值，不能简单理解为“CPU 核心数越多，阈值固定放大几倍”。线程池是否异常，核心看 PendingWorkItemCount 是否持续堆积，以及堆积期间 CompletedWorkItemRatePerSecond、活跃 Worker/IO 线程和业务延迟是否同步恶化。

最实用的估算方式：

待处理队列阈值 = 正常峰值每秒完成数量 * 可接受排队秒数

例如某接口高峰期每秒完成约 1000 个工作项，业务最多接受 100ms 排队：

1000/s * 0.1s = 100

此时可先设置：

new ThreadPoolMonitorOptions
{
    SampleIntervalMs = 5000,
    PendingWorkItemWarningThreshold = 50,
    PendingWorkItemCriticalThreshold = 100,
    AlertConsecutiveSamples = 2,
};

常用起步配置：

推荐的现场校准步骤：

1. 先用默认值上线观察，不直接作为最终告警规则。
2. 记录正常高峰期的 PendingWorkItemCount、CompletedWorkItemRatePerSecond 和接口延迟。
3. 将 Warning 设置为正常高峰 P99 Pending 的约 2 倍。
4. 将 Critical 设置为业务延迟开始不可接受时的 Pending，或 Warning 的 3-5 倍。
5. 使用 AlertConsecutiveSamples 过滤瞬时尖峰。采样间隔为 5000ms 且连续次数为 2 时，表示异常持续约 10 秒才触发关注。

WorkerThreadWarningHeadroom、WorkerThreadCriticalHeadroom、IoThreadWarningHeadroom 和 IoThreadCriticalHeadroom 是接近最大线程数时的兜底告警。默认 .NET 运行时的 MaxWorkerThreads 往往很大，例如几万级，因此不要只依赖它判断线程池问题；更可靠的信号是 PendingWorkItemCount 持续大于 0，同时完成速率下降或业务延迟升高。

不要为了让告警更容易触发而随意调低 ThreadPool.SetMaxThreads。如果 Pending 偶尔堆积、约 500ms 后恢复，通常优先评估 MinThreads 是否偏低；如果 Pending 持续堆积并且 Worker 增长，优先排查 .Result、Wait()、Thread.Sleep()、长同步锁和同步 IO。

Demo 控制台

dotnet run --project BugFree.Core.Demo

运行后选择 1) 线程池监控，控制台会启动 ThreadPoolMonitor 并临时排队一批阻塞工作项，用于观察 PendingWorkItemCount、活跃 Worker 线程、完成速率和告警输出。

排查建议

• 队列长度持续上涨：优先排查 .Result / Wait() / Thread.Sleep() / 长同步锁。
• 活跃 Worker 接近最大值：抓取 Dump 或查看线程堆栈，定位长期阻塞代码。
• Pending 偶尔堆积后恢复：可能是 MinThreads 偏低导致突发任务等待线程池扩容，需结合业务峰值评估。
• IOCP 线程持续接近上限：优先检查数据库、网络、文件 IO 是否使用异步 API。
• 未观测任务异常上涨：检查未 await 的 fire-and-forget 任务，并在任务内部捕获异常。
• 临时线上排查可使用 dotnet-counters monitor -p <PID> System.Threading.ThreadPool。

诊断辅助 API

var command = ThreadPoolDiagnosticCommands.CreateDotnetCountersCommand(Environment.ProcessId);
var eventCounters = ThreadPoolDiagnosticCommands.EventCounterNames;
var perfMonCounters = ThreadPoolDiagnosticCommands.PerfMonCounterNames;
var linuxCommands = ThreadPoolDiagnosticCommands.CreateLinuxDiagnosticCommands(Environment.ProcessId);

内置 EventCounter 名称包括：

• threadpool-worker-thread-count
• threadpool-io-thread-count
• threadpool-pending-work-item-count
• threadpool-completed-work-item-count
• threadpool-adjustment-interval-ms

需要注意：库内实时采集走 ThreadPool 公开 API，保持跨平台、低开销、无后台监听器；PerfMon、Dump、dotnet-counters、Prometheus/OpenTelemetry 更适合做外部诊断和长期可视化。

🎮 受控资源容量演示（ResourceStressController）

概述

ResourceStressController 是一个受控资源压力和容量演示工具，用于在演示、压测或验收环境中模拟 CPU、内存、磁盘空间占用。它会根据整机资源使用率动态加压或释放，并默认启用安全上限和业务优先释放策略。

主要用途：

• 进行容量演示和硬件资源验证
• 进行压力测试和性能评估
• 模拟高负载场景下的系统行为
• 验证系统在资源紧张时的稳定性

注意：该工具会主动制造额外负载，不应作为生产常驻任务静默运行。生产环境如果临时启用，必须配合外部开关、运行时长上限、监控告警和应急停止手段。

架构设计

Tools/ResourceStress/
├── ResourceStressController.cs         # 统一入口，编排所有生成器
├── ResourceStressSnapshot.cs           # 状态快照
├── Configuration/                      # 对外配置模型
│   ├── ResourceStressOptions.cs        # 总配置 + 安全演示默认配置
│   ├── CpuStressOptions.cs             # CPU 配置
│   ├── MemoryStressOptions.cs          # 内存配置
│   └── DiskStressOptions.cs            # 磁盘配置
├── Generators/                         # 内部压力生成器
│   ├── IResourceGenerator.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{业务优先\n超过目标缓冲?}
    E -->|是| D
    E -->|否| F[闭环缺口填充\ngap/perUnit × Damping]
    F --> G[调整负载单元\n线程/内存块/文件]
    G --> A
    D --> A

控制策略说明：

1. EMA指数平滑：使用指数移动平均算法消除系统监控数据的尖峰噪声
2. 安全检查：当资源使用率超过安全上限时，立即释放本工具制造的负载
3. 业务优先释放：当真实业务负载把资源推高到目标值以上时，优先让出本工具占用的资源
4. 闭环缺口填充：根据目标使用率与当前使用率的差值，动态调整资源负载
5. 自适应调节：支持滞后恢复，防止在安全边界频繁切换状态

使用示例

using BugFree.Core.Tools.ResourceStress;
using BugFree.Core.Tools.ResourceStress.Configuration;

// 安全容量演示默认配置：默认启用 CPU + 内存，磁盘需显式开启
var options = ResourceStressOptions.CreateCapacityDemoDefaults(includeDisk: false);
using var ctrl = new ResourceStressController(options);

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

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

配置说明

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 = CharsetType.AlphaNumericUpper,
    ExcludeConfusingCharacters = true
};
string code = SecureRandomStringGenerator.Generate(options);

// 6. 递增字符串
string nextCode = IncrementalStringGenerator.Next("009", CharsetType.Numeric, 3); // "010"
string[] batchCodes = IncrementalStringGenerator.GenerateRange(CharsetType.Numeric, 100_000, startIndex: 0, minLength: 6);
string customPaddedCode = IncrementalStringGenerator.FromIndex(9, CharsetType.Numeric, 3, paddingCharacter: '_'); // "__9"

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

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

// 9. 特性获取
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/               # 工具类
    ├── ResourceStress/                 # 受控资源容量演示与压力生成
    │   ├── Configuration/              # CPU/内存/磁盘配置
    │   ├── Generators/                 # 压力生成器
    │   └── Platform/                   # 跨平台系统监控
    ├── ThreadPoolMonitoring/          # 线程池指标采集、健康评估和告警
    └── Charset/
        ├── CharsetType.cs                 # 预定义字符集
        ├── SecureRandomStringGenerator.cs # 安全随机字符串
        └── IncrementalStringGenerator.cs  # 递增字符串

🛠️ 技术要求

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

🤝 参与贡献

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