Healnet.Common 2.0.3

Healnet.Common 通用模块

版本: v1.5.0 | TFM: net10.0 | 独立引用 | NuGet: Healnet.Common 1.5.0

概述

Healnet.Common 是 Healnet 微服务框架的基础通用工具类库，提供跨项目共享的加密工具、JSON 序列化、ID 生成器、扩展方法、DTO 基类和 Excel 处理等功能。作为整个框架的底层依赖，为 Core 和 Infrastructure 层提供基础支撑。

核心特性

• ✅ 加密工具 - AES/RSA/Hash 加密解密辅助方法 (CryptoHelper)
• ✅ JSON 序列化 - 高性能 JSON 序列化/反序列化 (JsonHelper)
• ✅ 雪花 ID - 分布式唯一 ID 生成器 (IdGenerator)
• ✅ 扩展方法 - String/Object/DateTime/Collection 扩展方法
• ✅ DTO 基类 - AuditableDto/BaseDto/PaginationDto 通用数据传输对象
• ✅ Excel 处理 - 基于 ClosedXML 的 Excel 导入导出 (ExcelService)
• ✅ Mapster 映射 - Mapster 扩展配置 (MapsterExtensions)
• ✅ FluentValidation - 验证器扩展方法 (FluentValidationExtensions)
• ✅ 业务枚举 - 通用业务枚举定义 (BusinessEnums)
• ✅ 应用常量 - 系统级常量定义 (AppConstants)
• ✅ 集成事件 - 分布式事件基础类型 (IntegrationEvent)

核心组件

1. 工具类 (Helpers)

2. 扩展方法 (Extensions)

3. 数据传输对象 (Models)

4. 文件存储 (FileStorage)

5. 其他模块

依赖关系

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

使用指南

1. 加密工具

using Healnet.Common.Helpers;

// AES 加密/解密
string plaintext = "Hello World";
string key = CryptoHelper.GenerateAesKey();
string encrypted = CryptoHelper.AesEncrypt(plaintext, key);
string decrypted = CryptoHelper.AesDecrypt(encrypted, key);

// SHA256 哈希
string hash = CryptoHelper.Sha256Hash("password123");

// MD5 哈希
string md5 = CryptoHelper.Md5Hash("password123");

2. JSON 序列化

using Healnet.Common.Helpers;

var obj = new { Name = "Healnet", Version = "1.5.0" };

// 序列化为 JSON 字符串
string json = JsonHelper.Serialize(obj);

// 反序列化
var result = JsonHelper.Deserialize<MyModel>(json);

// 安全序列化（处理循环引用）
string safeJson = JsonHelper.SerializeSafe(obj);

3. 雪花 ID 生成

using Healnet.Common.Helpers;

// 默认实例
long id = IdGenerator.GenerateId();

// 自定义实例（设置数据中心和工作区 ID）
var customGenerator = new IdGenerator(datacenterId: 1, workerId: 1);
long customId = customGenerator.GenerateId();

4. 扩展方法

using Healnet.Common.Extensions;

// 字符串扩展
string name = "  Hello World  ";
string trimmed = name.TrimEx();           // 智能修剪
bool isEmpty = name.IsEmpty();            // 判空（含空白字符）
string base64 = name.ToBase64();          // Base64 编码
string decoded = base64.FromBase64();     // Base64 解码

// 集合扩展
var list = new List<int> { 1, 2, 3, 4, 5, 6 };
var paged = list.ToPagedList(1, 2);      // 分页
var grouped = list.GroupByBatch(2);       // 分批

5. DTO 基类

using Healnet.Common.Models;

// 基础 DTO
public class UserDto : BaseDto
{
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
}

// 可审计 DTO
public class OrderDto : AuditableDto
{
    public string OrderNo { get; set; } = string.Empty;
    public decimal TotalAmount { get; set; }
}

// 分页查询参数
public class QueryParams : PaginationDto
{
    public string? Keyword { get; set; }
    public DateTime? StartDate { get; set; }
}

6. Excel 处理

using Healnet.Common.FileStorage.Excel;

// 导出数据到 Excel
var data = new List<UserDto> { /* ... */ };
await excelService.ExportAsync(data, "users.xlsx");

// 从 Excel 导入数据
var imported = await excelService.ImportAsync<UserDto>("users.xlsx");

NuGet 包信息

版本历史

| 版本 | 日期 | 变更说明 | |------|------|----------| | v1.5.0 | 2026-06-16 | 新增 EnvironmentHelper、NetworkHelper、RandomHelper、ServiceAddressHelper；重构 IdGenerator；移除 Newtonsoft.Json 依赖；标记 StringHelper 为 Obsolete | | v1.4.0 | - | 版本统一升级 | }

### 2. 工具类使用

```csharp
// 字符串工具
string trimmed = StringHelper.TrimToNull("  hello  ");  // "hello"
string hash = StringHelper.GenerateHash("password");     // 哈希值
bool isEmail = StringHelper.IsEmail("test@example.com"); // true
string mask = StringHelper.MaskEmail("test@example.com"); // "t***@example.com"

// 日期时间工具
DateTime now = DateTimeHelper.Now;                      // 当前 UTC 时间
string formatted = DateTimeHelper.Format(DateTime.Now, "yyyy-MM-dd HH:mm:ss");
DateTime parsed = DateTimeHelper.Parse("2024-01-01");
int days = DateTimeHelper.GetDaysBetween(startDate, endDate);
bool isWorkDay = DateTimeHelper.IsWorkDay(DateTime.Now);

// 集合工具
List<int> list = CollectionHelper.EmptyIfNull(nullList);
bool hasItems = CollectionHelper.HasItems(list);
List<int> distinct = CollectionHelper.RemoveDuplicates(list);
Dictionary<string, int> dict = CollectionHelper.ToDictionary(list, item => item.ToString());

// 加密工具
string encrypted = EncryptionHelper.Encrypt("secret", "key");
string decrypted = EncryptionHelper.Decrypt(encrypted, "key");
string md5 = EncryptionHelper.Md5Hash("text");
string sha256 = EncryptionHelper.Sha256Hash("text");
string token = EncryptionHelper.GenerateToken();

// 验证工具
bool isValid = ValidationHelper.IsValidEmail("test@example.com");
bool isMobile = ValidationHelper.IsValidMobile("13800138000");
bool isIdCard = ValidationHelper.IsValidIdCard("110101199003077758");
bool isUrl = ValidationHelper.IsValidUrl("https://example.com");

3. 扩展方法使用

// 字符串扩展
string str = "Hello World";
bool isNullOrEmpty = str.IsNullOrEmpty();           // false
bool isNotNullOrEmpty = str.IsNotNullOrEmpty();     // true
string trimmed = str.SafeTrim();                    // "Hello World"
string lower = str.ToLowerInvariant();              // "hello world"
string upper = str.ToUpperInvariant();              // "HELLO WORLD"
bool contains = str.ContainsIgnoreCase("world");    // true
string substring = str.SafeSubstring(0, 5);         // "Hello"
string[] split = str.SplitTrim(',');               // ["Hello World"]

// 日期时间扩展
DateTime date = DateTime.Now;
string formatted = date.ToStandardFormat();         // "2024-01-15 10:30:00"
string dateOnly = date.ToDateString();              // "2024-01-15"
string timeOnly = date.ToTimeString();              // "10:30:00"
bool isToday = date.IsToday();                      // true
bool isYesterday = date.IsYesterday();              // false
DateTime startOfDay = date.StartOfDay();            // 00:00:00
DateTime endOfDay = date.EndOfDay();                // 23:59:59
DateTime nextWeek = date.AddWeeks(1);               // 一周后

// 集合扩展
List<int> numbers = new List<int> { 1, 2, 3, 4, 5 };
bool isNullOrEmpty = numbers.IsNullOrEmpty();       // false
bool hasItems = numbers.HasItems();                 // true
int? first = numbers.FirstOrNull();                 // 1
int? last = numbers.LastOrNull();                   // 5
List<int> even = numbers.WhereNotNull();            // 过滤空值
List<string> strList = numbers.Select(x => x.ToString()).ToList();

// 对象扩展
object obj = null;
bool isNull = obj.IsNull();                         // true
bool isNotNull = obj.IsNotNull();                   // false
string json = obj.ToJson();                         // "null"
T clone = obj.Clone();                              // 深拷贝

// 枚举扩展
OrderStatus status = OrderStatus.Pending;
string name = status.GetName();                     // "Pending"
string description = status.GetDescription();       // "待处理"
int value = status.GetValue();                      // 1
bool hasFlag = status.HasFlag(OrderStatus.Pending); // true

4. 分页结果

public class UserService
{
    public PagedResult<User> GetPagedUsers(int page, int pageSize)
    {
        var query = _userRepository.GetAllQueryable();
        var totalCount = query.Count();
        var items = query.Skip((page - 1) * pageSize).Take(pageSize).ToList();
        
        return new PagedResult<User>
        {
            Items = items,
            Page = page,
            PageSize = pageSize,
            TotalCount = totalCount,
            TotalPages = (int)Math.Ceiling((double)totalCount / pageSize)
        };
    }
}

// 使用
var result = userService.GetPagedUsers(1, 10);
foreach (var user in result.Items)
{
    Console.WriteLine(user.Name);
}

Console.WriteLine($"共 {result.TotalCount} 条，共 {result.TotalPages} 页");

5. 通用结果类型

public Result<string> ValidateInput(string input)
{
    if (string.IsNullOrEmpty(input))
    {
        return Result<string>.Failure("输入不能为空");
    }
    
    if (input.Length < 6)
    {
        return Result<string>.Failure("输入长度不能小于6");
    }
    
    return Result<string>.Success(input);
}

// 使用
var result = ValidateInput("test");
if (result.IsSuccess)
{
    Console.WriteLine($"有效输入: {result.Data}");
}
else
{
    Console.WriteLine($"错误: {result.Message}");
}

6. 配置帮助类

// 从配置获取字符串
string connectionString = ConfigurationHelper.GetString("ConnectionStrings:Default");

// 从配置获取整数
int timeout = ConfigurationHelper.GetInt("AppSettings:Timeout", 30);

// 从配置获取布尔值
bool enabled = ConfigurationHelper.GetBool("AppSettings:Enabled", true);

// 从配置获取对象
var settings = ConfigurationHelper.GetSection<AppSettings>("AppSettings");

// 强类型配置
public class AppSettings
{
    public string ApiUrl { get; set; } = string.Empty;
    public int Timeout { get; set; } = 30;
    public bool EnableLogging { get; set; } = true;
}

// 使用 IOptions
public class MyService
{
    private readonly AppSettings _settings;
    
    public MyService(IOptions<AppSettings> settings)
    {
        _settings = settings.Value;
    }
    
    public void DoSomething()
    {
        Console.WriteLine($"API URL: {_settings.ApiUrl}");
    }
}

7. 反射工具

// 获取类型属性
var properties = ReflectionHelper.GetProperties<User>();

// 获取属性值
object value = ReflectionHelper.GetPropertyValue(user, "Name");

// 设置属性值
ReflectionHelper.SetPropertyValue(user, "Name", "New Name");

// 检查类型是否实现接口
bool implements = ReflectionHelper.ImplementsInterface<User, IEntity>();

// 创建实例
User user = ReflectionHelper.CreateInstance<User>();

// 获取方法
MethodInfo method = ReflectionHelper.GetMethod<User>("GetById");

// 调用方法
object result = ReflectionHelper.InvokeMethod(user, "ToString");

常量定义示例

public static class ClaimTypes
{
    public const string UserId = "sub";
    public const string Email = "email";
    public const string Role = "role";
    public const string Name = "name";
    public const string TenantId = "tenantId";
    public const string Permissions = "permissions";
}

public static class CacheKeys
{
    public const string UserPrefix = "User:";
    public const string TokenPrefix = "Token:";
    public const string ConfigPrefix = "Config:";
    
    public static string User(long userId) => $"{UserPrefix}{userId}";
    public static string RefreshToken(string token) => $"{TokenPrefix}{token}";
}

public static class PolicyNames
{
    public const string AdminOnly = "AdminOnly";
    public const string ManagerOrAdmin = "ManagerOrAdmin";
    public const string TenantAccess = "TenantAccess";
}

public static class HttpHeaders
{
    public const string Authorization = "Authorization";
    public const string ContentType = "Content-Type";
    public const string XRequestId = "X-Request-Id";
    public const string XTenantId = "X-Tenant-Id";
}

依赖包

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Options" Version="8.0.0" />

项目结构

┌─────────────────────────────────────────────────────────────┐
│                    Healnet.Common                          │
├─────────────────────────────────────────────────────────────┤
│  Helpers                                                   │
│  ├── StringHelper.cs                                       │
│  ├── DateTimeHelper.cs                                     │
│  ├── CollectionHelper.cs                                   │
│  ├── EncryptionHelper.cs                                   │
│  ├── ValidationHelper.cs                                   │
│  ├── ReflectionHelper.cs                                   │
│  └── ConfigurationHelper.cs                                │
├─────────────────────────────────────────────────────────────┤
│  Extensions                                                │
│  ├── StringExtensions.cs                                   │
│  ├── DateTimeExtensions.cs                                 │
│  ├── CollectionExtensions.cs                               │
│  ├── ObjectExtensions.cs                                   │
│  └── EnumExtensions.cs                                     │
├─────────────────────────────────────────────────────────────┤
│  Models                                                    │
│  ├── ApiResponse.cs                                       │
│  ├── PagedResult.cs                                        │
│  ├── Result.cs                                             │
│  └── AuditInfo.cs                                         │
├─────────────────────────────────────────────────────────────┤
│  Constants                                                 │
│  ├── ClaimTypes.cs                                         │
│  ├── CacheKeys.cs                                          │
│  ├── PolicyNames.cs                                        │
│  └── HttpHeaders.cs                                        │
└─────────────────────────────────────────────────────────────┘