Healnet.Common 3.0.0

Healnet.Common 通用模块

版本: v2.0.6 | TFM: net10.0 | 独立引用（零上层依赖） | NuGet: Healnet.Common 2.0.6

概述

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

⚠️ 重要变更（2.x）：原 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 加解密
string key = CryptoHelper.GenerateAesKey();
string encrypted = CryptoHelper.AesEncrypt("Hello", key);
string decrypted = CryptoHelper.AesDecrypt(encrypted, key);

2. JSON 序列化

using Healnet.Common.Helpers;

var obj = new { Name = "Healnet", Version = "2.0.6" };
string json = JsonHelper.Serialize(obj);
var result = JsonHelper.Deserialize<MyModel>(json);
string safeJson = JsonHelper.Serialize(obj, new JsonSerializerOptions { WriteIndented = true });

3. 雪花 ID 生成

using Healnet.Common.Helpers;

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

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

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 包信息

版本历史