Sage.Data.Extensions 1.0.0.10

Sage.Data.Extensions

简介

Sage.Data.Extensions 提供了一系列常用的数据类型扩展方法，简化了日常开发中的常见操作。该库设计为线程安全，并完全兼容 AOT 编译。

特性

• 字符串扩展方法（判空、格式化、类型转换等）
• 日期时间扩展方法（格式化、时间段计算等）
• 字节数组扩展方法（编码转换、哈希计算等）
• 整型和长整型扩展方法（范围检查、格式化等）
• 字典扩展方法（条件添加、转换为查询字符串等）
• 线程安全设计
• 完全兼容 AOT 编译

安装

dotnet add package Sage.Data.Extensions

使用示例

字符串扩展方法 (StringExtensions)

空值检查和默认值处理

// 判断字符串是否为空（null、空字符串或仅包含空白字符）
string text = "";
bool isEmpty = text.IsEmpty(); // 返回 true

string text2 = "  ";
bool isEmpty2 = text2.IsEmpty(); // 返回 true

string text3 = "Hello";
bool isEmpty3 = text3.IsEmpty(); // 返回 false

// 判断字符串是否为null或空字符串（不考虑空白字符）
string text4 = "  ";
bool isNullOrEmpty = text4.IsNullOrEmpty(); // 返回 false

// 设置默认值
string nullText = null;
string result = nullText.DefaultIfEmpty("N/A"); // 返回 "N/A"

类型转换

// 字符串转整数
string numText = "123";
int num = numText.ToInt(); // 返回 123

// 自动处理非数字字符
string mixedText = "a123b";
int num2 = mixedText.ToInt(); // 返回 123

// 转换失败时使用默认值
string invalidText = "abc";
int num3 = invalidText.ToInt(10); // 返回 10

// 转换为其他数值类型
string longText = "9876543210";
long longNum = longText.ToLong();

string shortText = "123";
short shortNum = shortText.ToShort();

字节数组扩展方法 (ByteExtensions)

编码转换

// 转换为Base64字符串
byte[] data = Encoding.UTF8.GetBytes("Hello World");
string base64 = data.ToBase64String(); // 返回 "SGVsbG8gV29ybGQ="

// 转换为十六进制字符串
byte[] bytes = { 0xFF, 0x00, 0xAB };
string hex = bytes.ToHexString(); // 返回 "FF00AB"
string hexLower = bytes.ToHexStringLower(); // 返回 "ff00ab"

// 转换为URL安全的Base64
byte[] urlData = Encoding.UTF8.GetBytes("Hello+World/=");
string urlSafe = urlData.ToUrlSafeBase64(); // 返回不含+、/和=的Base64字符串

// 转换为UTF-8字符串
byte[] utf8Bytes = Encoding.UTF8.GetBytes("Hello 世界");
string text = utf8Bytes.ToUtf8String(); // 返回 "Hello 世界"

哈希计算

// 计算HMAC-SHA1
byte[] data = Encoding.UTF8.GetBytes("重要数据");
string key = "secret-key";
byte[] hmacBytes = data.ToHmacSha1(key);

// 转换为Base64用于存储或传输
string signature = Convert.ToBase64String(hmacBytes);

日期时间扩展方法 (DateTimeExtensions)

友好格式化

// 根据与当前日期的关系格式化日期
DateTime now = DateTime.Now;
string formatted = now.ToFriendlyDateString(); // 返回如 "14:30"

DateTime yesterday = DateTime.Now.AddDays(-1);
string formatted2 = yesterday.ToFriendlyDateString(); // 返回如 "12日 14:30"

// 日志格式化
string logTime = now.ToLogFormat(); // 返回 "2023-12-20 14:30:45"
string logTimeWithMs = now.ToLogFormat(true); // 返回 "2023-12-20 14:30:45.123"

日期计算

// 获取日期的开始和结束时间
DateTime date = DateTime.Now;
DateTime dayStart = date.StartOfDay(); // 返回当天 00:00:00.000
DateTime dayEnd = date.EndOfDay(); // 返回当天 23:59:59.999

// 获取周、月、季度、年的开始和结束
DateTime weekStart = date.StartOfWeek(); // 返回本周一 00:00:00.000
DateTime monthStart = date.StartOfMonth(); // 返回本月1日 00:00:00.000
DateTime monthEnd = date.EndOfMonth(); // 返回本月最后一天 23:59:59.999
DateTime quarterStart = date.StartOfQuarter(); // 返回本季度第一天 00:00:00.000
DateTime yearStart = date.StartOfYear(); // 返回本年1月1日 00:00:00.000

// 工作日判断
bool isWorkday = date.IsWeekday(); // 如果是周一至周五返回true
bool isWeekend = date.IsWeekend(); // 如果是周六或周日返回true

// 日期差异计算
DateTime futureDate = DateTime.Now.AddDays(10);
int daysUntil = DateTime.Now.DaysUntil(futureDate); // 返回10

// Unix时间戳转换
long timestamp = date.ToUnixTimestamp(); // 返回Unix时间戳（秒）
long timestampMs = date.ToUnixTimestampMs(); // 返回Unix时间戳（毫秒）

整型扩展方法 (IntExtensions)

范围检查和限制

// 判断数值是否在指定范围内
int age = 25;
bool isAdult = age.Between(18, 100); // 返回 true

// 限制数值在指定范围内
int score = 150;
int clampedScore = score.Clamp(0, 100); // 返回 100

int volume = -5;
int safeVolume = volume.Clamp(0, 100); // 返回 0

时间转换

// 将整数转换为TimeSpan
int timeout = 30; // 30秒
TimeSpan timeoutSpan = timeout.Seconds();

int cacheMinutes = 15;
TimeSpan expiry = cacheMinutes.Minutes();

int sessionHours = 2;
TimeSpan session = sessionHours.Hours();

int retentionDays = 30;
TimeSpan retention = retentionDays.Days();

数值格式化和判断

// 转换为二进制和十六进制字符串
int number = 10;
string binary = number.ToBinary(); // 返回 "1010"

int color = 255;
string hex = color.ToHexString(); // 返回 "FF"
string hexLower = color.ToHexString(false); // 返回 "ff"

// 判断奇偶性
int value = 42;
bool isEven = value.IsEven(); // 返回 true
bool isOdd = value.IsOdd(); // 返回 false

// 重复执行操作
var items = new List<string>();
5.Times(i => items.Add($"Item {i + 1}")); // 添加5个项目到列表

长整型扩展方法 (LongExtensions)

文件大小格式化

// 格式化文件大小
long fileSize = 1536; 
string size1 = fileSize.ToFileSizeString(); // 返回 "1.50 KB"
string size2 = fileSize.ToFileSizeString(0); // 返回 "2 KB"

long largeSize = 1073741824; 
string size3 = largeSize.ToFileSizeString(); // 返回 "1.00 GB"

时间戳转换

// Unix时间戳转换为DateTime
long timestamp = 1609459200; // 2021-01-01 00:00:00 UTC
DateTime date = timestamp.FromUnixTimestamp(); 

// 毫秒时间戳转换
long timestampMs = 1609459200000; // 2021-01-01 00:00:00.000 UTC
DateTime dateMs = timestampMs.FromUnixTimestampMs();

其他操作

// 范围检查和限制
long score = 85;
bool isPassing = score.Between(60, 100); // 返回 true

long value = 150;
long clampedValue = value.Clamp(0, 100); // 返回 100

// 毫秒转TimeSpan
long duration = 5000; // 5秒
TimeSpan timeSpan = duration.ToTimeSpan();

// 判断奇偶性
long number = 42;
bool isEven = number.IsEven(); // 返回 true
bool isOdd = number.IsOdd(); // 返回 false

字典扩展方法 (DictionaryExtensions)

// 定义枚举
public enum MemberStatus
{
    Inactive = 0,
    Active = 1,
    Suspended = 2,
    Premium = 3
}
public enum OrderType
{
    Online = 1,
    Offline = 2,
    Wholesale = 3
}
public enum PaymentMethod
{
    Cash,
    Card,
    Alipay,
    WeChat
}
public enum Gender
{
    Unknown = 0,
    Male = 1,
    Female = 2
}
public enum SortOrder
{
    Asc,
    Desc
}

var businessParams = new Dictionary<string, object>
{
["member_id"] = memberId
}
.AddIfNotEmpty("keywords", keywords)
.AddIfGreaterThan("page", page)
.AddIfGreaterThan("pagesize", pagesize)
    
// ✨ 枚举转数字
.AddIfValid("status", status,
    s => s.HasValue,
    s => (int)s!.Value)
    
// ✨ 枚举转自定义字符串
.AddIfValid("order_type", orderType,
    t => t.HasValue,
    t => t!.Value switch
{
    OrderType.Online => "online_order",
    OrderType.Offline => "offline_order",
    OrderType.Wholesale => "wholesale_order",
    _ => "unknown"
})
    
// ✨ 枚举转API代码
.AddIfValid("payment_method", paymentMethod,
    p => p.HasValue,
    p => p!.Value switch
{
    PaymentMethod.Cash => "CASH_001",
    PaymentMethod.Card => "CARD_002",
    PaymentMethod.Alipay => "ALIPAY_003",
    PaymentMethod.WeChat => "WECHAT_004",
    _ => "UNKNOWN_000"
})
    
// ✨ 有条件的枚举转换（只有非Unknown时才添加）
.AddIfValid("gender", gender,
    g => g.HasValue && g.Value != Gender.Unknown,
    g => (int)g!.Value)
    
// ✨ 枚举转布尔值
.AddIfValid("is_desc", sortOrder,
    s => s.HasValue,
    s => s!.Value == SortOrder.Desc)
    
// ✨ 布尔值转数字
.AddIfValid("is_vip", isVip,
    v => v.HasValue,
    v => v!.Value ? 1 : 0)
    
// ✨ 布尔值转字符串
.AddIfValid("include_deleted", includeDeleted,
    d => d.HasValue,
    d => d!.Value ? "yes" : "no")
    
// ✨ 复杂条件 + 多重转换
.AddIfValid("priority_level", status,
    s => s.HasValue && (s.Value == MemberStatus.Premium || s.Value == MemberStatus.Active),
    s => s!.Value switch
{
    MemberStatus.Premium => 100,
    MemberStatus.Active => 50,
    _ => 0
})
    
// ✨ 日期时间转时间戳
.AddIfValid("created_after_timestamp", createdAfter,
    d => d.HasValue && d.Value > DateTime.MinValue,
    d => ((DateTimeOffset)d!.Value).ToUnixTimeSeconds())
    
// ✨ 组合条件：只有VIP且状态为Active时才添加特殊标识
.AddIfValid("special_flag", status,
    s => s.HasValue && s.Value == MemberStatus.Premium && isVip == true,
    s => "VIP_PREMIUM")
    
// ✨ 多枚举组合逻辑
.AddIfValid("service_level", new { Status = status, OrderType = orderType },
    combo => combo.Status.HasValue && combo.OrderType.HasValue,
    combo => (combo.Status!.Value, combo.OrderType!.Value) switch
{
    (MemberStatus.Premium, OrderType.Wholesale) => "enterprise",
    (MemberStatus.Premium, _) => "premium",
    (MemberStatus.Active, OrderType.Wholesale) => "business",
    (MemberStatus.Active, _) => "standard",
    _ => "basic"
});

// 转换为查询字符串
var queryString = businessParams.ToQueryString();

// 转换为 JSON
var jsonString = businessParams.ToJsonString();

更多方法查看代码文档。

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交问题报告和改进建议。如果您想贡献代码，请提交拉取请求。

作者

• LiuPengLai - 甲壳虫科技 欢迎提交问题和功能请求。 QQ Group: 1054304346