Pirates.Core 4.2.8

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Pirates.Core --version 4.2.8
                    


                    

                
NuGet\Install-Package Pirates.Core -Version 4.2.8
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Pirates.Core" Version="4.2.8" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Pirates.Core" Version="4.2.8" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Pirates.Core" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Pirates.Core --version 4.2.8
                    


                    

                
#r "nuget: Pirates.Core, 4.2.8"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Pirates.Core@4.2.8
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Pirates.Core&version=4.2.8
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Pirates.Core&version=4.2.8
                    


                            Install as a Cake Tool

Pirates.Core 核心类库

项目简介

Pirates.Core 是一个功能强大的 .NET 核心类库，提供了丰富的工具类、扩展方法和云服务集成，旨在简化企业级应用开发。

主要功能模块

1. 控制器基类 (Controller)

提供多种控制器基类，支持不同场景的 API 开发：

  • BaseController - 基础控制器，提供通用功能
  • BaseApiController - 面向客户端的 API 控制器，包含认证和请求信息
  • BaseAdminController - 管理后台控制器，包含角色和权限验证
  • BaseUserController - 用户控制器基类
使用示例
// API 控制器
public class UserController : BaseApiController
{
    public IActionResult GetInfo()
    {
        var requestId = RequestId;  // 请求唯一标识
        var clientIp = ClientIp;    // 客户端真实IP
        return Ok(UserData);
    }
}

// 管理后台控制器
[Authorize(Roles = "Admin")]
public class AdminController : BaseAdminController
{
    public IActionResult DeleteUser(string userId)
    {
        ValidatePermission("UserDelete");  // 权限验证
        if (IsSuperAdmin) { /* 超级管理员逻辑 */ }
        return Ok();
    }
}

2. JWT 认证 (JWT)

完整的 JWT 令牌生成、验证和管理功能：

  • Token - 令牌数据模型，包含用户信息和角色
  • JwtHelper - JWT 加密解密帮助类
  • 支持角色声明、过期时间管理、令牌验证
使用示例
// 生成令牌
var token = new Token
{
    Uid = "user123",
    UserName = "张三",
    Role = "Admin,User"
};

var result = JwtHelper.Encrypt(token, isExpires: true, expiresTime: 30);

// 解析令牌
var decodeResult = JwtHelper.Decode(tokenString);

// 验证令牌
var isValid = JwtHelper.Validate(tokenString);

3. 文件上传 (Files)

支持多种云存储服务的文件上传和删除：

  • 本地存储 (localhost)
  • 阿里云 OSS (aliyun)
  • 腾讯云 COS (tencent)
  • 华为云 OBS (huawei)
  • 七牛云 Kodo (qiniu)
功能特性
  • ✅ 文件类型验证
  • ✅ 文件大小限制
  • ✅ 自动生成缩略图
  • ✅ 安全路径检查（防止路径遍历攻击）
  • ✅ 异步上传/删除操作
使用示例
// 上传文件到阿里云 OSS
var result = await Upload.PutObject(fileBytes, "image.jpg", "aliyun");
if (result.IsSuccess)
{
    var fileUrl = result.Data.Url;         // 文件URL
    var thumbUrl = result.Data.Thumb;      // 缩略图URL
}

// 删除文件
var deleteResult = await Upload.Delete("/upload/20240101/image.jpg", "aliyun");

4. Redis 缓存 (NoSql/Redis)

高性能 Redis 缓存操作封装：

  • RedisUtil - Redis 操作入口，支持多数据库
  • RedisString - 字符串操作
  • RedisHash - 哈希操作
  • RedisList - 列表操作
  • RedisSet - 集合操作
  • RedisSortedSet - 有序集合操作
使用示例
// 字符串操作
await RedisUtil.StringSetAsync("user:123", userData, TimeSpan.FromHours(1));
var user = await RedisUtil.StringGetAsync<User>("user:123");

// 哈希操作
await RedisUtil.HashSetAsync("user:123", "name", "张三");
var name = await RedisUtil.HashGetAsync("user:123", "name");

// 列表操作
await RedisUtil.ListRightPushAsync("queue", message);
var msg = await RedisUtil.ListLeftPopAsync("queue");

5. 扩展方法 (Extensions)

丰富的扩展方法集合，提升开发效率：

字符串扩展 (StringExtensions)
// 验证
var isEmail = email.IsValidEmail();
var isPhone = phone.IsValidPhone();
var isIdCard = idCard.IsValidIdCard();

// 转换
var list = "1,2,3".ToIntList();
var array = "a,b,c".ToStringArray();

// 安全处理
var maskedPhone = phone.Mask();  // 138****1234
var maskedEmail = email.MaskEmail();  // j***@example.com
整数扩展 (IntExtensions)
// 范围限制
var clamped = value.Clamp(0, 100);
var inRange = value.InRange(0, 100);

// 判断
var isEven = number.IsEven();
var isOdd = number.IsOdd();

// 格式化
var size = bytes.ToFileSizeString();  // "1.5 MB"
var formatted = number.ToThousandSeparator();  // "1,234"

// 重复执行
5.Times(() => Console.WriteLine("Hello"));
5.Times(i => Console.WriteLine(i));  // 0,1,2,3,4
列表扩展 (ListExtensions)
// 分页
var page = list.Page(1, 10);

// 随机操作
var random = list.Random();
var randomItems = list.RandomTake(5);
list.Shuffle();  // 打乱顺序

// 安全获取
var item = list.GetOrDefault(5);
var first = list.FirstOrDefaultSafe();
var last = list.LastOrDefaultSafe();

// 拆分
var batches = list.SplitList(100);  // 每100个一组
字典扩展 (DictionaryExtensions)
// 添加或更新
dict.AddOrUpdate("key", "value");
dict.AddOrUpdate(otherDict);

// 获取或添加
var value = dict.GetOrAdd("key", () => "default");

// 遍历
dict.ForEach((key, value) => Console.WriteLine($"{key}: {value}"));

// 转换
var url = dict.ToUrl();  // "key1=value1&key2=value2"
时间扩展 (DateExtensions)
// 时间戳
var timestamp = DateTime.Now.ToTimestamp();
var dateTime = timestamp.ToTimestampLong();

// 日期范围
var monthStart = date.GetMonthStart();
var monthEnd = date.GetMonthEnd();
var weekStart = date.GetWeekStart();
var weekEnd = date.GetWeekEnd();

// 判断
var isWorkday = date.IsWorkday();
var isWeekend = date.IsWeekend();
var age = birthDate.GetAge();

// 友好时间
var friendly = dateTime.ToFriendlyString();  // "3天前"
JSON 扩展 (JsonExtensions)
// 序列化
var json = obj.ToJson();

// 反序列化
var user = json.ToEntity<User>();
var list = json.ToList<User>();
验证扩展 (ValidationExtensions)
// 数据验证
var isValid = obj.TryValidate(out var errors);
var isValid = obj.TryValidate(out string errorMessage);

// 格式验证
var isValidEmail = email.IsValidEmail();
var isValidPhone = phone.IsValidPhone();
var isValidUrl = url.IsValidUrl();
var isValidIdCard = idCard.IsValidIdCard();

// 集合验证
var isEmpty = collection.IsNullOrEmpty();
var hasItems = collection.HasItems();

// 枚举验证
var isValidEnum = value.IsValidEnum();

6. 云服务集成 (Cloud)

阿里云服务
  • OSS - 对象存储（文件上传/删除）
  • SMS - 短信服务
  • IoT - 物联网平台
腾讯云服务
  • COS - 对象存储
  • 微信 - 公众号、小程序、企业微信
华为云服务
  • OBS - 对象存储
七牛云服务
  • Kodo - 对象存储
其他服务
  • 支付宝 - 支付、OAuth
  • 高德地图 - 地理位置
  • 极光推送 - 消息推送
  • 网易云 - IM、直播、点播
  • 微信 - 支付、模板消息

7. 安全工具 (Security)

  • EncryptionHelper - 加密帮助类
    • MD5 哈希
    • SHA256 哈希
    • AES 加密/解密
    • Base64 编码/解码
    • URL 安全的 Base64
    • 安全随机数生成
使用示例
// MD5
var hash = EncryptionHelper.Md5("password");
var saltedHash = EncryptionHelper.Md5WithSalt("password", "salt");

// SHA256
var sha256 = EncryptionHelper.Sha256("data");

// AES
var encrypted = EncryptionHelper.AesEncrypt(plainText, key, iv);
var decrypted = EncryptionHelper.AesDecrypt(cipherText, key, iv);

// Base64
var encoded = EncryptionHelper.Base64Encode("text");
var decoded = EncryptionHelper.Base64Decode(encoded);

// 随机数
var randomStr = EncryptionHelper.GenerateRandomString(32);
var randomNum = EncryptionHelper.GenerateRandomNumber(6);  // 验证码
var secureBytes = EncryptionHelper.GenerateSecureRandomBytes(32);

8. 配置管理 (Config)

  • AppSettings - 应用程序配置管理
  • App - 应用全局状态
  • JsonConfigUtils - JSON 配置工具
使用示例
// 读取配置
var value = AppSettings.Get("Section:Key");
var defaultValue = AppSettings.GetWithDefault("default", "Section:Key");
var intValue = AppSettings.GetInt(0, "Section:IntKey");
var boolValue = AppSettings.GetBool(false, "Section:BoolKey");

// 检查初始化
if (AppSettings.IsInitialized)
{
    // 配置已加载
}

9. 常量定义 (Const)

  • CacheConst - 缓存键常量

    • 预定义缓存键前缀
    • 过期时间配置
    • 缓存键构建辅助方法

  • SqlSugarConst - 数据库常量

    • 数据库标识
    • 分页配置
    • 排序常量

  • Permissions - 权限常量

    • 角色定义
    • 策略名称
使用示例
// 缓存键
var userKey = CacheConst.BuildUserKey("123");  // "user:123"
var verCodeKey = CacheConst.BuildVerCodeKey("phone");  // "verCode:phone"

// 过期时间
var expiration = CacheConst.DefaultExpiration;  // 1800秒 (30分钟)
var shortExpiration = CacheConst.ShortExpiration;  // 300秒 (5分钟)

// 权限
var isAdmin = user.HasRole(Permissions.SuperAdmin);

10. 通用工具类 (Common)

Guard - 参数守卫类
// 空值检查
Guard.NotNull(obj, nameof(obj));
Guard.NotNullOrEmpty(str, nameof(str));
Guard.NotNullOrWhiteSpace(str, nameof(str));
Guard.NotNullOrEmpty(list, nameof(list));

// 范围检查
Guard.GreaterThanZero(number, nameof(number));
Guard.InRange(value, min, max, nameof(value));

// 条件检查
Guard.IsTrue(condition, "条件必须为真");
Guard.IsFalse(condition, "条件必须为假");

// 类型检查
var typedObj = Guard.IsType<MyClass>(obj, nameof(obj));
Result - 通用结果类
// 成功结果
var result = Result.Success("操作成功");
var result = Result.Success(data, "操作成功");

// 失败结果
var result = Result.Failure("操作失败", 500);
var result = Result.BadRequest("参数错误");
var result = Result.NotFound("资源不存在");

// 泛型结果
var result = Result<User>.Success(user);
var result = Result<User>.Failure("用户不存在", 404);

// 使用示例
if (result.IsSuccess)
{
    var data = result.Data;
}
else
{
    var error = result.Message;
    var code = result.Code;
}
TimeUtil - 时间工具类
// 时间戳
var timestampMs = TimeUtil.GetTimestampMs();
var timestampSec = TimeUtil.GetTimestampSec();

// 转换
var timestamp = dateTime.ToTimestampMs();
var dateTime = TimeUtil.FromTimestampMs(timestamp);

// 日期范围
var monthStart = date.GetMonthStart();
var monthEnd = date.GetMonthEnd();
var dayStart = date.GetDayStart();
var dayEnd = date.GetDayEnd();
var weekStart = date.GetWeekStart();
var weekEnd = date.GetWeekEnd();

// 判断
var age = birthDate.GetAge();
var isWorkday = date.IsWorkday();
var isWeekend = date.IsWeekend();

// 友好时间
var friendly = dateTime.ToFriendlyString();  // "3天前"
var days = TimeUtil.GetDaysBetween(start, end);

11. 数据访问层 (DataBase)

基于 SqlSugar ORM 的数据访问封装：

  • BaseRepository - 基础仓储类
  • RepositoryByT - 泛型仓储
  • SqlSugarHelper - SqlSugar 帮助类
功能特性
  • 支持多数据库
  • 异步操作
  • 分页查询
  • 事务管理
  • 软删除支持

12. 过滤器 (Filters)

  • AuthorizationFilter - 授权过滤器
  • JwtAuthorizationFilter - JWT 授权过滤器
  • ValidationFilter - 模型验证过滤器
  • GlobalExceptionsFilter - 全局异常过滤器
  • RateLimitFilter - 限流过滤器
  • GlobalAllowAnonymousFilter - 全局匿名访问过滤器

13. AI 服务集成 (Ai)

支持多种 AI 大模型：

  • DeepSeek - DeepSeek AI
  • 豆包 - 字节跳动豆包
  • 通义 - 阿里通义千问

14. 消息队列 (Kafka)

  • Kafka 生产者/消费者封装
  • 异步消息发送/接收

15. 日志记录 (Logger)

  • Log4Net - 日志记录
  • NLog - 日志记录

16. 定时任务 (HangFire/Quartz)

  • HangFire - 后台任务调度
  • Quartz - 定时任务调度

17. 服务注册 (Consul/Nacos)

  • Consul - 服务注册与发现
  • Nacos - 配置中心与服务发现

快速开始

1. 安装依赖

dotnet add package Pirates.Core

2. 配置服务

// Program.cs 或 Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    // 添加 Pirates.Core 服务
    services.AddPiratesCore();
    
    // 配置 Redis
    services.AddRedis();
    
    // 配置 JWT
    services.AddJwtAuthentication();
    
    // 配置其他服务...
}

3. 使用示例

// 控制器中使用
public class UserController : BaseApiController
{
    private readonly IUserService _userService;
    
    public UserController(IUserService userService)
    {
        _userService = userService;
    }
    
    [HttpGet("{id}")]
    public async Task<IActionResult> GetUser(string id)
    {
        // 从缓存获取
        var cacheKey = CacheConst.BuildUserKey(id);
        var user = await RedisUtil.StringGetAsync<User>(cacheKey);
        
        if (user == null)
        {
            // 从数据库获取
            user = await _userService.GetByIdAsync(id);
            
            // 写入缓存
            await RedisUtil.StringSetAsync(cacheKey, user, TimeSpan.FromHours(1));
        }
        
        return Result<User>.Success(user);
    }
    
    [HttpPost]
    public async Task<IActionResult> CreateUser(CreateUserRequest request)
    {
        // 参数验证
        Guard.NotNullOrEmpty(request.Name, nameof(request.Name));
        Guard.NotNullOrEmpty(request.Email, nameof(request.Email));
        
        if (!request.Email.IsValidEmail())
            return Result.BadRequest("邮箱格式不正确");
        
        // 创建用户
        var user = await _userService.CreateAsync(request);
        
        return Result<User>.Success(user, "创建成功");
    }
}

最佳实践

1. 参数验证

// 使用 Guard 进行参数验证
public async Task UpdateUser(string userId, UpdateUserRequest request)
{
    Guard.NotNullOrEmpty(userId, nameof(userId));
    Guard.NotNull(request, nameof(request));
    Guard.NotNullOrEmpty(request.Name, nameof(request.Name));
    Guard.InRange(request.Age, 0, 150, nameof(request.Age));
    
    // 业务逻辑...
}

2. 缓存使用

// 缓存读取模式
public async Task<User> GetUserAsync(string userId)
{
    var cacheKey = CacheConst.BuildUserKey(userId);
    
    // 尝试从缓存获取
    var user = await RedisUtil.StringGetAsync<User>(cacheKey);
    if (user != null)
        return user;
    
    // 从数据库获取
    user = await _repository.GetByIdAsync(userId);
    
    // 写入缓存
    if (user != null)
    {
        await RedisUtil.StringSetAsync(cacheKey, user, TimeSpan.FromMinutes(30));
    }
    
    return user;
}

3. 错误处理

// 使用 Result 封装返回结果
public async Task<Result<User>> GetUserAsync(string userId)
{
    try
    {
        Guard.NotNullOrEmpty(userId, nameof(userId));
        
        var user = await _repository.GetByIdAsync(userId);
        if (user == null)
            return Result<User>.NotFound("用户不存在");
        
        return Result<User>.Success(user);
    }
    catch (Exception ex)
    {
        Logger.Log4Net.Singleton.Error("获取用户失败", ex);
        return Result<User>.Failure("获取用户失败");
    }
}

4. 文件上传

// 安全的文件上传
public async Task<Result<Models.Files.Upload>> UploadFile(IFormFile file)
{
    if (file == null || file.Length == 0)
        return Result<Models.Files.Upload>.BadRequest("文件不能为空");
    
    // 读取文件字节
    using var ms = new MemoryStream();
    await file.CopyToAsync(ms);
    var bytes = ms.ToArray();
    
    // 上传到云存储
    var result = await Upload.PutObject(bytes, file.FileName, "aliyun");
    
    return result.IsSuccess 
        ? Result<Models.Files.Upload>.Success(result.Data)
        : Result<Models.Files.Upload>.Failure(result.Message);
}

项目结构

Pirates.Core/
├── Ai/                 # AI 服务集成
├── Apollo/             # Apollo 配置中心
├── Cloud/              # 云服务集成
├── Code/               # 错误码定义
├── Config/             # 配置管理
├── Const/              # 常量定义
├── Consul/             # Consul 服务注册
├── Controller/         # 控制器基类
├── Data/               # 数据模型
├── DataBase/           # 数据访问层
├── DateTimeExt/        # 时间扩展
├── Extensions/         # 扩展方法
├── Files/              # 文件上传
├── Filters/            # 过滤器
├── Handler/            # 处理器
├── HangFire/           # 后台任务
├── Helper/             # 帮助类
├── Http/               # HTTP 客户端
├── ImCore/             # 即时通讯
├── JWT/                # JWT 认证
├── JsonConfig/         # JSON 配置
├── Kafka/              # 消息队列
├── Logger/             # 日志记录
├── Models/             # 数据模型
├── Nacos/              # Nacos 配置中心
├── NoSql/              # NoSQL 数据库
│   └── Redis/          # Redis 缓存
├── Options/            # 配置选项
├── Quartz/             # 定时任务
├── Security/           # 安全工具
├── Startup/            # 启动配置
├── Strings/            # 字符串工具
└── Utility/            # 通用工具

依赖项

  • .NET 8.0+ - 运行环境
  • SqlSugar - ORM 框架
  • CSRedis - Redis 客户端
  • Newtonsoft.Json - JSON 处理
  • JWT - JSON Web Token
  • Log4Net/NLog - 日志框架
  • HangFire/Quartz - 任务调度
  • Consul/Nacos - 服务发现

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请通过以下方式联系：

  • 提交 Issue
  • 发送邮件

Pirates.Core - 让 .NET 开发更简单、更高效！

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Pirates.Core:

Package Downloads
Pirates.Admin.Common

My package description.
Pirates.Common

My package description.
Prates.Common

My package description.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
4.3.2 62 5/6/2026
4.3.1 104 4/14/2026
4.3.0 91 4/14/2026
4.2.9 95 4/14/2026
4.2.8 91 4/14/2026
4.2.7 97 3/23/2026
4.2.6 101 2/26/2026
4.2.5 95 2/25/2026
4.2.4 120 2/5/2026
4.2.3 237 11/25/2025
4.2.2 223 11/25/2025
4.2.1 428 11/21/2025
4.2.0 307 11/11/2025
4.1.9 304 11/11/2025
4.1.8 305 11/11/2025
4.1.7 298 11/11/2025
4.1.6 237 9/30/2025
4.1.5 256 9/23/2025
4.1.4 319 9/15/2025
4.1.3 252 9/15/2025
Loading failed