YellowJHelp 4.2.0
dotnet add package YellowJHelp --version 4.2.0
NuGet\Install-Package YellowJHelp -Version 4.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="YellowJHelp" Version="4.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="YellowJHelp" Version="4.2.0" />
<PackageReference Include="YellowJHelp" />
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add YellowJHelp --version 4.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: YellowJHelp, 4.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package YellowJHelp@4.2.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=YellowJHelp&version=4.2.0
#tool nuget:?package=YellowJHelp&version=4.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
YellowJAutoInjection & YellowJHelp
简介
YellowJAutoInjection 和 YellowJHelp 是一套面向 .NET 平台的高性能、低依赖、易扩展的开发工具库，涵盖自动依赖注入、对象映射、缓存、分布式ID、日志、加解密、集合算法等常用功能，适配 .NET Framework 4.6.1、.NET Standard 2.0/2.1/9。
YellowJHelp
YellowJHelp 是一个面向 .NET 平台的通用开发工具库，主要用于提升企业级项目的开发效率和代码质量。它集成了常用的开发辅助功能，包括但不限于：
- 加解密：支持 MD5、DES、SHA256、AES 等多种算法，异步实现，适合高并发场景。
- 日志记录：支持异步、分级、分目录、文件流等方式，便于归档和分析。
- Session/Cookie 管理：适配 ASP.NET Core，支持常用 Web 状态管理。
- 集合与数据处理：分配算法、去重、合并、差集、交集等，支持多线程和异步。
- 高性能对象映射器（FastMapper）：属性名自动匹配、类型兼容、集合/嵌套递归，零依赖，性能极高。
- 分布式ID生成：雪花ID算法，适合分布式系统唯一ID需求。
- 缓存接口（YJHelpCache）：支持泛型、过期策略、内存和分布式缓存。
- Kafka/Redis 支持：消息队列与高性能缓存。
- 异步优先：大部分方法支持异步，适合高并发场景。
YellowJAutoInjection
依赖注入自动化
- 零配置自动注入，通过特性标记和程序集扫描，自动完成服务注册。
- 兼容主流IOC容器，支持 .NET Core/6/7/8/9 及 .NET Framework。
- 极简用法，无需手动注册服务，提升开发效率。
主要方法说明
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| YJDiInJect | - | void | 自动扫描并注入所有特性服务 |
| [AutoInject] 特性 | Type | - | 标记自动注入的接口或类 |
快速上手
- 安装 NuGet 包
- 在 Startup.cs 中调用
YJDiInJect() - 在服务类上添加
[AutoInject]特性
案列：Net9
builder.Services.YJDiInJect();
类库中满足如：
[AutoInject(typeof(ILoginServer))]
声明的都将自动注入程序集
YellowJHelp
通用开发工具库
- 高性能对象映射器（FastMapper）：属性名自动匹配、类型兼容、集合/嵌套递归，零依赖，性能极高。
- 多线程集合处理：支持大数据量分配、去重、合并等操作。
- 缓存/分布式ID/日志/加解密：一站式解决常见开发需求。
- 异步优先：3.0.0+ 版本方法基本异步，适合现代高并发场景。
主要方法说明
YJHelp（核心方法）
| 方法名 | 参数说明 | 返回值 | 功能详细描述 |
|---|---|---|---|
| 加密模块 | |||
| MD5EncryptAsync | strText, isLower | Task<string> | 生成32位MD5哈希值，适用于密码存储/数据校验 |
| EncodeAsync | data, KEY_64, IV_64 | Task<string> | DES对称加密，用于敏感数据传输 |
| DecodeAsync | data, KEY_64, IV_64 | Task<string> | DES解密，需与加密使用相同密钥 |
| YJSha256Async | text | Task<string> | SHA256哈希加密，适用于签名、完整性校验 |
| YJAesEncryptAsync | plainText, key, iv | Task<string> | AES加密，支持128/192/256位，返回Base64字符串 |
| YJAesDecryptAsync | cipherText, key, iv | Task<string> | AES解密，输入Base64密文，返回明文 |
| 日志与文件 | |||
| YellowJLogAsync | text, address, logLevel, customFileName | Task | 按日期/分级/分目录异步写日志，UTF8编码 |
| MidStrExAsync | sourse, startstr, endstr | Task<string> | 提取两个标识符之间的内容，适用于解析特定格式文本 |
| HTTP状态管理 | |||
| SetCookies | ctx, key, value, minutes | void | 设置客户端Cookie，默认30分钟过期 |
| DeleteCookies | ctx, key | void | 清除指定Cookie |
| GetCookies | ctx, key | string | 读取Cookie值，不存在时返回空字符串 |
| SessionAdd | ctx, strSessionName, strValue | void | 存储Session数据(二进制格式) |
| SessionGet | ctx, cancellationToken | Task | 异步加载Session数据 |
| SessionDel | ctx, strSessionName | void | 移除指定Session |
| 数据处理 | |||
| IsString | data, value | bool | 检查字符串是否包含指定内容(不区分大小写) |
| YAlloctionlist | yAllocations, yAllocations1 | List<List<YAllocationInfo>> | 资源分配核心算法，返回[剩余资源, 已分配明细, 分配结果] |
| YAlloctionlistThred | yAllocations, yAllocations1 | List<List<YAllocationInfo>> | 多线程版分配算法，提升大数据量处理效率 |
| DistinctAsync<T, TKey> | list, keySelector | Task<List<T>> | 异步根据指定字段去重，生成全新且不扰动原集合的列表 |
| ToDictAsync<TSource, TKey> | list, keySelector, allowDuplicate | Task<Dictionary<TKey, TSource>> | 异步将集合转换为字典，支持自定义Key和重复Key处理 |
| ToDictAsync<TSource, TKeyItem> | list, keySelector, allowDuplicate | Task<Dictionary<string, TSource>> | 异步将集合Key（如List<string>）序列化为字符串作为字典Key |
| ID与对象 | |||
| NextId | workerId | long | 生成分布式雪花ID(基于WorkerID) |
| IsDateInTargetMonth | date, targetDate | bool | 判断日期是否在目标年月内 |
| Copy<T> | data | T? | 深度克隆对象(使用DeepCloner库) |
| YJMerge<T> | list1, list2 | List<T> | 合并两个集合并去重(JSON序列化比对) |
| Distinct<T> | list | List<T> | 集合去重(基于哈希表实现) |
FastMapper（高性能对象映射器）
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| Adapt<TTarget> | this object source | TTarget | 自动推断源类型，返回新对象 |
| Adapt<TSource,TTarget> | this TSource source | TTarget | 泛型映射，类型安全 |
| Adapt<TTarget> | this object source, TTarget dest | TTarget | 属性覆盖到已存在对象 |
| Adapt<List<TTarget>> | this IEnumerable<object> sourceList | List<TTarget> | 集合递归映射 |
YJHelpCache
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| TryGetValue | key, out value | bool | 判断是否存在并返回字符串值 |
| Get | key | object | 获取缓存（支持泛型） |
| Get<T> | key | T | 泛型获取缓存对象 |
| Set | key, value, options | string | 写入缓存（string） |
| Set<T> | key, value, options | void | 泛型写入缓存 |
| Remove | key | void | 删除缓存 |
YJFlowGuard（API 限流）
| 方法名 | 参数说明 | 返回值 | 功能详细描述 |
|---|---|---|---|
| CheckAccessAsync | key, limitCount, timeWindowSeconds | Task<bool> | 检查是否允许访问（固定窗口算法） |
| CheckAccessSlidingWindowAsync | key, limitCount, timeWindowSeconds | Task<bool> | 检查是否允许访问（滑动窗口算法） |
| GetStatusAsync | key | Task<FlowGuardStatus> | 获取当前限流状态 |
| ResetAsync | key | Task | 重置限流计数 |
特性说明：
- 固定窗口算法：简单高效，适合一般场景，按固定时间窗口统计请求数
- 滑动窗口算法：更平滑，适合高精度场景，按滑动时间窗口统计请求数
- 自动依赖注入：参考 YJDiInJect 的使用方式，零配置自动注入
- 兼容 .NET Standard 2.0/2.1：使用反射兼容旧版本，支持多框架
- 灵活配置：支持 Controller 和 Action 级别限流
- 自定义标识：支持自定义限流 key，便于精细化控制
- 动态占位符：支持
{userId}、{ip}、{path}、{method}等占位符 - 日志记录：自动记录限流触发日志，便于监控和排查
快速上手：
- 在 Startup.cs 或 Program.cs 中注册服务
// 添加限流服务（会自动注入相关依赖）
services.AddYJFlowGuard();
// 使用限流中间件
app.UseYJFlowGuard();
- 在 Controller 或 Action 上添加限流特性
[ApiController]
[Route("api/[controller]")]
// 对整个 Controller 限流：60秒内最多100次请求
[FlowGuard(100, 60)]
public class UserController : ControllerBase
{
[HttpGet("{id}")]
// 对单个 Action 限流：10秒内最多5次请求
[FlowGuard(5, 10)]
public async Task<IActionResult> GetUser(int id)
{
// 业务逻辑
return Ok();
}
}
- 动态 Key 使用（支持占位符）
// 按用户 ID 限流
[FlowGuard(10, 60, key: "order_create_{userId}")]
// 按 IP 地址限流
[FlowGuard(5, 60, key: "login_{ip}")]
// 组合占位符
[FlowGuard(3, 3600, key: "export_{userId}_{path}")]
// 使用滑动窗口算法
[FlowGuard(100, 60, strategy: FlowGuardStrategy.SlidingWindow)]
// 自定义限流提示信息
[FlowGuard(100, 60, message: "您的请求过于频繁，请稍后再试")]
支持的占位符：
| 占位符 | 说明 | 示例 Key | 实际 Key |
|---|---|---|---|
{userId} |
用户 ID（从 JWT Token 或 Claims 中获取） | order_{userId} |
order_user123 |
{ip} |
客户端 IP 地址 | login_{ip} |
login_192.168.1.100 |
{path} |
请求路径 | api_{path} |
api_/api/data |
{method} |
HTTP 方法（GET/POST/PUT/DELETE） | {method}_api |
get_api |
实际应用场景：
// 场景一：防止暴力破解登录
[HttpPost("login")]
[FlowGuard(10, 3600, key: "login_attempt_{ip}", message: "登录尝试次数过多，请1小时后再试")]
public async Task<IActionResult> Login([FromBody] LoginRequest request)
{
// 验证用户名密码
return Ok(new { token = "jwt_token" });
}
// 场景二：防止恶意刷短信
[HttpPost("send")]
[FlowGuard(1, 60, key: "sms_{phone}", message: "短信发送过于频繁，请稍后再试")]
public async Task<IActionResult> SendSms([FromBody] SendSmsRequest request)
{
// 发送短信验证码
return Ok(new { message = "验证码已发送" });
}
// 场景三：保护关键资源
[HttpGet("export")]
[FlowGuard(5, 3600, key: "report_export_{userId}", message: "报表导出次数已达上限")]
public async Task<IActionResult> ExportReport()
{
// 生成报表
return File(new byte[0], "application/pdf", "report.pdf");
}
// 场景四：API 分级限流
[ApiController]
[Route("api/[controller]")]
// 整个 Controller 每秒最多 1000 次请求
[FlowGuard(1000, 1)]
public class ApiController : ControllerBase
{
[HttpGet("public")]
// 每个 IP 每秒最多 10 次请求
[FlowGuard(10, 1, key: "public_{ip}")]
public async Task<IActionResult> GetPublicData()
{
return Ok(new { data = "public data" });
}
[HttpGet("user")]
// 每个用户每秒最多 20 次请求
[FlowGuard(20, 1, key: "user_{userId}")]
[Authorize]
public async Task<IActionResult> GetUserData()
{
return Ok(new { data = "user data" });
}
}
限流响应：
当触发限流时，返回 HTTP 429 状态码：
{
"code": 429,
"message": "请求过于频繁，请稍后再试",
"data": null
}
使用场景：
- API 接口保护：防止恶意请求和 DDoS 攻击
- 资源限流：保护数据库、第三方服务等关键资源
- 用户限流：按用户或 IP 限制请求频率
- 接口分级：不同接口设置不同的限流策略
最佳实践：
| 场景 | 限流次数 | 时间窗口 | 算法 |
|---|---|---|---|
| 登录接口 | 5-10 次 | 1 小时 | 固定窗口 |
| 短信验证码 | 1 次 | 1 分钟 | 固定窗口 |
| 数据查询 | 10-100 次 | 1 秒 | 滑动窗口 |
| 文件导出 | 3-5 次 | 1 小时 | 固定窗口 |
| 支付接口 | 5-10 次 | 1 分钟 | 滑动窗口 |
注意事项：
- 限流计数存储在内存缓存中，重启后会重置
- 建议根据业务场景合理设置限流参数
- 可结合日志监控限流触发情况，优化限流策略
- 分布式环境：如果需要跨服务器共享限流计数，建议使用 Redis 等分布式缓存
- 用户 ID 获取：确保 JWT Token 或 Claims 中包含用户 ID 信息
📚 更多详细示例：
查看 FlowGuardUsageExamples.md 获取更多详细的使用示例和最佳实践，包括：
- 动态 Key 的完整使用说明
- 5 个实际应用场景详解
- 常见问题解答
- JWT Token 配置示例
YJHelpKafka
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| Produce | topic, value | void | 发布消息 |
| ProduceAdmin | topic, value, user, pwd | void | 发布消息（带账号） |
| ProduceAdminPartition | topic, value, user, pwd | void | 随机分区发布（带账号） |
YJHelpRedis
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| RedisCli | - | RedisClient | Redis 配置中心 |
| Get | key | object | 获取单个实体 |
| GetList | key | List<object> | 获取列表 |
| Add | key, value | void | 添加（已存在时不更新） |
| ListSetW/T | key, value | void | 集合写入 |
| Clear/Remove | key | void | 清空/删除 |
| GetExpire | key | TimeSpan | 获取有效期 |
| ContainsKey | key | bool | 判断是否存在 |
| Count/SCARD | key | int | 获取集合个数 |
YJHelpT
| 方法名 | 参数说明 | 返回值 | 功能描述 |
|---|---|---|---|
| SpliteSourceBySize | list, size | List<List<T>> | 按大小分组 |
| SpliteSourceByCount | list, count | List<List<T>> | 按组数分组 |
| DistinctList | list | List<T> | 集合去重（数值类型） |
| Merge/MergeC | list1, list2 | List<T> | 合并集合 |
| DiffsetT/Diffset | list1, list2 | List<T> | 差集 |
| Intersect/Union | list1, list2 | List<T> | 交集/并集 |
历史版本（摘自 NuGet 包说明）
- 3.7.6： 新增 API 限流功能（YJFlowGuard），支持固定窗口和滑动窗口算法
- 3.7.5： 新增SHA256哈希加密,AES加密,AES解密
- 3.7.4： 新增Mapster风格的替代方案
- 3.7：新增lis集合生成字典的方法，方便快速查询：ToDictAsync, 优化其它逻辑和新增集合去重逻辑
- 3.5：新增对象深拷贝、对象映射器、雪花ID等功能，优化减少依赖，移除 sqlsugar
- 3.4：新增多线程集合处理、IYJHelpCache 缓存接口
- 3.0.0+：方法基本改为异步
- 2.2.0：自动依赖注入功能独立为 YellowJAutoInjection
- 2.0.0：结构优化，新增 Server 层和 IServer 层
安装与使用
- NuGet 安装
- 参考示例代码和注释
- 详细API请查阅源码或接口文档
参与贡献
欢迎提交 Issue、PR 或建议！
第三方依赖与致谢
本项目部分功能基于以下优秀开源组件，特此致谢：
| 依赖库 | 说明 | 链接 |
|---|---|---|
| Confluent.Kafka | 高性能 Kafka 客户端 | https://github.com/confluentinc/confluent-kafka-dotnet |
| NewLife.Redis | 分布式缓存/Redis客户端 | https://github.com/NewLifeX/NewLife.Redis |
| DeepCloner | 对象深拷贝 | https://github.com/force-net/DeepCloner |
感谢所有开源社区的贡献者！
相关链接
如需更多详细用法、扩展或定制，请查阅源码或联系作者。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
.NETStandard 2.0
- Confluent.Kafka (>= 2.8.0)
- DeepCloner (>= 0.10.4)
- Microsoft.AspNetCore.Http.Abstractions (>= 2.3.0)
- Microsoft.Extensions.Caching.Memory (>= 9.0.2)
- NewLife.Redis (>= 6.1.2025.209)
- System.Net.Http (>= 4.3.4)
- System.Text.Json (>= 9.0.2)
- System.Text.RegularExpressions (>= 4.3.1)
- YellowJAutoInjection (>= 2.1.0)
-
.NETStandard 2.1
- Confluent.Kafka (>= 2.8.0)
- DeepCloner (>= 0.10.4)
- Microsoft.AspNetCore.Http.Abstractions (>= 2.3.0)
- Microsoft.Extensions.Caching.Memory (>= 9.0.2)
- NewLife.Redis (>= 6.1.2025.209)
- System.Net.Http (>= 4.3.4)
- System.Text.Json (>= 9.0.2)
- System.Text.RegularExpressions (>= 4.3.1)
- YellowJAutoInjection (>= 2.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
修复DistinctAsync的方法影响原值的情况