WingWell.Util

通用工具类库，提供类型安全转换、异常体系、HTTP 请求、加密、JSON、文件操作等开箱即用的基础能力。

功能一览

快速开始

dotnet add package WingWell.Util -s https://nuget.wingwell.cloud/v3/index.json

类型安全转换

所有外部输入的类型转换使用 Get* 系列，转换失败返回默认值，不抛异常：

int val = GetInt.FromObject(obj);              // 默认 0
int val = GetInt.FromObject(obj, -1);          // 自定义默认值
decimal price = GetDecimal.FromObject(obj);
bool flag = GetBoolean.FromObject(obj);        // 支持 1/0, true/false, yes/no
string str = GetString.FromObject(obj);

编码互转：

string base64 = GetBase64.FromBytes(buffer);
string base64 = GetBase64.FromStream(stream);
byte[] buf = GetBuffer.FromBase64(base64);
MemoryStream ms = GetStream.FromBase64(base64);

异常体系

// 业务异常
throw BusinessException.Get(MethodBase.GetCurrentMethod(),
    ExceptionInfoType.Business, "订单不存在", new { orderId });

// 消息提示（前端弹窗）
throw MessageException.Get(MethodBase.GetCurrentMethod(), "请先完成审批", null);

// 权限不足
throw ForbiddenException.Get(MethodBase.GetCurrentMethod(), "无权限访问", new { userId });

异常分类（ExceptionInfoType）：

API 响应模型

// 成功
return new ResponseModel<UserDto>(userData);

// 分页
return new ResponseModel<DataList<UserDto>>(new DataList<UserDto>
{
    Count = totalCount,
    Data = userList
});

ID 生成

基于 RandomNumberGenerator 的密码学安全随机数生成：

string id = NewCode.ULID;           // 26 位 ULID（推荐主键）
string id = NewCode.KeyId;          // 32 位 UUID（无横线大写）
string code = NewCode.NumberToken;  // 6 位数字验证码
string pwd = NewCode.Password;      // 12 位随机密码

HTTP 请求

var http = new HttpClientProvider();

// GET
string result = await http.GetAsync(url, authorization: "Bearer xxx");

// POST JSON
string result = await http.PostJsonAsync(url, json, authorization: "Bearer xxx");

// 单次请求覆盖超时
string result = await http.GetAsync(url, timeout: TimeSpan.FromSeconds(60));

// 流式请求（SSE / 大模型）
using var response = await http.PostJsonStreamingAsync(url, json,
    authorization: "Bearer xxx", cancellationToken: ct);

// 文件下载
byte[] buf = await http.GetBufferAsync(url);
string base64 = await http.GetBase64Async(url);

DI 注入：

var http = new HttpClientProvider(httpClient);

加密

哈希：

string hash = Md5Helper.GetMD5("data");       // 使用 MD5.HashData() 静态方法
string hash = Sha256Helper.Encrypt("data");    // 使用 SHA256.HashData() 静态方法

AES 加密（CBC 模式，自动随机 IV）：

var aes = new AesHelper("32位密钥");       // 必须传入密钥
string encrypted = aes.Encrypt("明文");    // 输出 Base64(IV + 密文)
string decrypted = aes.Decrypt(encrypted);

密码哈希（PBKDF2-SHA256，100000 次迭代，随机盐）：

string encrypted = PasswordHelper.Encrypt("password");        // 生成密文
bool ok = PasswordHelper.Verify("password", encrypted);       // 验证密码

JSON

string json = JsonHelper.Serialize(obj);
UserDto user = JsonHelper.Deserialize<UserDto>(json);

日期与时间戳

string day = DateHelper.GetDayString();                          // "2024-03-16"
string dur = DateHelper.GetDurationString(beginTime, endTime);   // "2小时30分钟"

long ts = UnixTimeHelper.GetUnixSeconds();
DateTime dt = UnixTimeHelper.GetDateTime(milliseconds);

文件操作

byte[] buf = FileHelper.ReadFileToBuffer(path);
string base64 = FileHelper.ReadFileToBase64(path);
FileHelper.SaveFileFromBuffer(path, buffer);
string size = FileHelper.FormatFileSize(1048576);  // "1 MB"

枚举工具

DataStatus? status = EnumHelper<DataStatus>.GetEnum("ACTIVE");
string desc = EnumHelper<DataStatus>.GetDescription("ACTIVE");
List<KeyTextSort> items = EnumHelper<DataStatus>.GetValues();

常用枚举

环境要求

• .NET 8.0+
• 依赖：Newtonsoft.Json、Ulid