Healnet.Common 4.0.10

Healnet.Common 通用模块

版本: v4.0.9 | TFM: net10.0 | 独立引用（零上层依赖） | NuGet: Healnet.Common 4.0.9

概述

Healnet.Common 是 Healnet 微服务框架的基础通用工具类库，提供跨项目共享的加密工具、JSON 序列化、分布式 ID 生成、扩展方法、DTO 基类、文件/Excel/Pdf 处理、Mapster 映射与 FluentValidation 验证等功能。作为整个框架的底层依赖（被 Core、Infrastructure 以及业务服务引用），Common 不引用任何上层模块，仅依赖少量通用 NuGet 包。

⚠️ 历史变更（工具类合并）：原 StringHelper、DateHelper、DateTimeHelper、CollectionHelper、EncryptionHelper、ReflectionHelper、ConfigurationHelper 等静态助手类已删除，其功能已并入对应的扩展方法类（StringExtensions / DateTimeExtensions / CollectionExtensions）或现有 Helper。请勿在新代码中引用这些已删除的类。

核心特性

• ✅ 加密工具 - CryptoHelper（PBKDF2 哈希、AES/RSA）、AESCrypto（AES 加解密）
• ✅ JSON 序列化 - JsonHelper（System.Text.Json 封装：序列化/反序列化/克隆/合并/格式化）
• ✅ 雪花 ID - IdGeneratorFactory + SnowflakeIdGenerator（分布式唯一 ID）
• ✅ 扩展方法 - StringExtensions / ObjectExtensions / DateTimeExtensions / CollectionExtensions
• ✅ DTO 基类 - BaseDto / AuditableDto / PaginationDto
• ✅ 文件存储 - IFileService / FileServiceBase / LocalFileService / OssFileService（抽象）+ ExcelService（ClosedXML）/ PdfService（QuestPDF）
• ✅ Mapster 映射 - MapsterExtensions
• ✅ FluentValidation - FluentValidationExtensions + ValidationService
• ✅ 业务枚举 - BusinessEnums
• ✅ 应用常量 - AppConstants（缓存键、HTTP 头、Claim 类型、日期格式、错误消息）
• ✅ 集成事件 - IntegrationEvent
• ✅ 网络/随机/验证/环境工具 - NetworkHelper / RandomHelper / ValidationHelper / EnvironmentHelper / ServiceAddressHelper

核心组件

1. 工具类 (Helpers) — 命名空间 Healnet.Common.Helpers

2. 扩展方法 (Extensions) — 命名空间 Healnet.Common.Extensions

3. 数据传输对象 (Models) — 命名空间 Healnet.Common.Models

⚠️ ApiResponse / PagedResult / Result 不存在于 Common（它们在 Healnet.Core.Responses）。

4. 文件存储 (FileStorage) — 命名空间 Healnet.Common.FileStorage

5. 其他模块

依赖关系

graph LR
    A[Healnet.Common] --> B[FluentValidation]
    A --> C[Mapster]
    A --> D[ClosedXML]
    A --> E[QuestPDF]
    A --> F[Microsoft.AspNetCore.Http.Abstractions]

使用指南

1. 加密与哈希

using Healnet.Common.Helpers;

// 密码哈希（自动随机盐值，无需手动传盐）
var hashed = CryptoHelper.HashPassword("myPassword");
var isValid = CryptoHelper.VerifyPassword("myPassword", hashed);

// 安全 Token（密码学安全随机）
var token = CryptoHelper.GenerateRandomString(32);

// AES 加解密（密钥须由调用方显式传入，用 GenerateRandomString 生成并妥善保存）
string key = CryptoHelper.GenerateRandomString(32);
string encrypted = CryptoHelper.AesEncrypt("Hello", key);
var (ok, decrypted) = CryptoHelper.AesDecrypt(encrypted, key);   // (bool Ok, string? Result)

// RSA 非对称加解密
var (pub, pri) = CryptoHelper.GenerateRsaKeyPair();
string rsaCipher = CryptoHelper.RsaEncrypt("Hello", pub);
string rsaPlain = CryptoHelper.RsaDecrypt(rsaCipher, pri);

⚠️ 历史提示：CryptoHelper.GenerateAesKey() 不存在——密钥请用 GenerateRandomString(32) 生成。 另有底层 AESCrypto.AESEncrypt/AESDecrypt(string, string)（Key 会被截断/补齐至 32 字符；解密失败返回 (false, null) 不抛异常）。

2. JSON 序列化

using Healnet.Common.Helpers;

var obj = new { Name = "Healnet", Version = "4.0.9" };
string json = JsonHelper.Serialize(obj);                       // camelCase、紧凑、null 字段不输出
var result = JsonHelper.Deserialize<MyModel>(json);            // 大小写不敏感
string pretty = JsonHelper.SerializeIndented(obj);             // 缩进格式
string formatted = JsonHelper.Format(json);                    // 美化已有 JSON
string minified = JsonHelper.Minify(pretty);                   // 压缩
string merged = JsonHelper.Merge("{\"a\":1}", "{\"a\":2,\"b\":3}"); // 后者覆盖前者 → {"a":2,"b":3}
bool valid = JsonHelper.IsValid(json);
int version = JsonHelper.GetProperty<int>(json, "version");    // 取字段值（强类型）
var clone = JsonHelper.Clone(obj);                             // JSON 深拷贝
byte[] bytes = JsonHelper.SerializeToBytes(obj);               // UTF-8 字节

⚠️ 非 ASCII 默认转义：Serialize 输出 "张三" 为 "\u5F20\u4E09"（合法 JSON，反序列化自动还原， 但日志肉眼可读性差）。需要原文输出时传入自定义 options：

var options = new JsonSerializerOptions(JsonHelper.DefaultOptionsShape())
{
    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};

3. 雪花 ID 生成

using Healnet.Common.Helpers;

// 默认实例
long id = IdGeneratorFactory.NewId();

// 自定义实例（数据中心 + 工作区）
var gen = IdGeneratorFactory.Create(workerId: 1, datacenterId: 1);
long customId = gen.NextId();
long[] batch = gen.NextIds(100);

// 解析 ID
long worker = gen.GetWorkerId(id);
long seq = gen.GetSequence(id);

🔴 已知缺陷（2026-11-02 单测发现，修复前请勿用 GetTimestamp）： SnowflakeOptions.StartTimestamp 默认取 .NET Ticks 纪元（公元 1 年起算），而时间戳区实际仅 36 位 （dc 5 + worker 10 + seq 12 = 27 位位移，与注释宣称的 41 位不符），36 位毫秒 ≈ 2.18 年—— 自 2026-03-08 起生成的雪花 ID 已溢出为负数（唯一性暂未破坏；GetTimestamp 解析出错误年份）。 修复需调整纪元与位分配（破坏性变更），修复后此警告将移除。单元测试见 tests/Healnet.Tests。

4. 扩展方法

using Healnet.Common.Extensions;

// 字符串
string name = "  Hello World  ";
bool isEmpty = name.IsNullOrWhiteSpace();
string base64 = name.ToBase64();
string masked = "13800138000".MaskPhone();           // "138****8000"
bool isEmail = "test@example.com".IsEmail();
string slug = "Hello World".ToSlug();                // "hello-world"

// 日期
DateTime now = DateTime.Now;
bool isWeekend = now.IsWeekend();
int days = now.GetDaysBetween(new DateTime(2026, 1, 1));
var ts = now.ToUnixTimestamp();

// 集合
var list = new List<int> { 1, 2, 3, 4, 5 };
var paged = list.Batch(2);                            // 分批
var safe = list.EmptyIfNull();

5. DTO 基类

using Healnet.Common.Models;

public class UserDto : AuditableDto
{
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
}

public class QueryParams : PaginationDto
{
    public string? Keyword { get; set; }
}

6. 文件 / Excel / Pdf

using Healnet.Common.FileStorage;
using Healnet.Common.FileStorage.Excel;

// Excel 导出/导入
var data = new List<UserDto> { /* ... */ };
await excelService.ExportAndSaveAsync(data, "users.xlsx");
var imported = await excelService.ImportFromSavedFileAsync<UserDto>("users.xlsx");

7. 依赖注入注册（分模块，无聚合入口）

// 各模块独立注册，Common 不提供 AddCommonServices 聚合方法
builder.Services.AddMapster();
builder.Services.AddFluentValidation();
builder.Services.AddFileService(opt => { /* FileStorageOptions */ });
builder.Services.AddExcelService();
builder.Services.AddPdfService();

NuGet 包信息

版本历史

以下变更说明整理自 Healnet.Common.csproj 的 PackageReleaseNotes，具体日期以各发布记录为准（本文不杜撰日期）。

许可证

MIT License