WitchC.FileStorage 1.2.0

WitchC Framework

╔═══════════════════════════════════════════════════╗
║                W i t c h C  🧙‍♀️                   ║
║            .NET 企业级应用开发框架              ║
║      (Wicked Intelligent .NET Core Framework)    ║
╚═══════════════════════════════════════════════════╝

📋 项目介绍

WitchC 是一个基于 .NET 8/9/10 的企业级应用开发框架，旨在提供简单、灵活、高效的开发体验。框架采用模块化设计，提供 21 个功能模块和 10 个扩展方法库，覆盖企业级应用开发的各个方面。

✨ 特性亮点

• 🚀 模块化架构 — 按需引入，轻量灵活
• 🔧 开箱即用 — 丰富的内置功能模块
• 📦 NuGet 发布 — 每个模块独立打包
• 🧪 测试驱动 — 83 个单元测试保障质量
• 📖 中文文档 — 完善的中文注释和文档
• 🎯 对标 Furion — 参考 Furion 设计，全部开源无锁定
• ⏰ 企业级调度 — 完整的 Cron 解析器、触发器系统、管理 Dashboard
• 📢 事件驱动 — 延迟发布、模糊匹配、重试机制、静态门面
• 🔄 约定式 DI — ITransient/IScoped/ISingleton 自动注册
• 📋 统一返回 — 标准化 API 响应格式、分页支持

📦 模块总览

核心模块

数据模块

通信模块

安全模块

存储模块

工具模块

🛠️ 扩展方法库

WitchC.Extensions 包含 10 个扩展方法模块：

🆕 v1.2 新增功能

定时任务增强

// 注册定时任务服务
builder.Services.AddWitchCSchedule(options =>
{
    options.EnableDashboard = true;  // 启用管理界面
});

// 方式 1: 使用 Cron 表达式
builder.Services.AddScheduledJob("cleanup", "0 2 * * *", async (context, ct) =>
{
    // 每天凌晨 2 点执行清理任务
    await CleanupAsync();
});

// 方式 2: 使用宏触发器
builder.Services.AddScheduledJob("heartbeat", MacroTriggerType.Minutely, async (context, ct) =>
{
    // 每分钟执行心跳检测
    await HeartbeatAsync();
});

// 方式 3: 使用 IJob 接口
builder.Services.AddScheduledJob<MyJob>(builder =>
{
    builder.WithCron("*/5 * * * *")  // 每 5 分钟
           .WithRetry(3, 2000)        // 重试 3 次，间隔 2 秒
           .WithTimeout(TimeSpan.FromMinutes(5));
});

// 使用管理界面
app.UseScheduleDashboard("/schedule");

事件总线增强

// 注册事件总线
builder.Services.AddWitchCEventBus(options =>
{
    options.EnableFuzzyMatch = true;  // 启用模糊匹配
});

// 发布事件
await eventBus.PublishAsync(new UserCreatedEvent { UserId = 123 });

// 延迟发布
await eventBus.PublishDelayAsync(new OrderTimeoutEvent { OrderId = 456 }, TimeSpan.FromMinutes(30));

// 按事件 ID 发布
await eventBus.PublishAsync("user.login", new { UserId = 123, Time = DateTime.Now });

// 订阅事件
eventBus.Subscribe("user.*", async (source, ct) =>
{
    // 模糊匹配所有 user. 开头的事件
    Console.WriteLine($"收到事件: {source.EventId}");
});

// 静态门面
await MessageCenter.PublishAsync(new NotificationEvent { Message = "Hello" });

依赖注入增强

// 注册约定式依赖注入
builder.Services.AddWitchCDependencyInjection();

// 实现标记接口即可自动注册
public interface IUserService { }
public class UserService : IUserService, ITransient { }  // 自动注册为瞬态

public interface ICacheService { }
public class CacheService : ICacheService, ISingleton { }  // 自动注册为单例

// 使用 InjectionAttribute 控制注册
[Injection(Pattern = InjectionPatterns.FirstInterface, Order = 10)]
public class MyService : IMyService, ITransient { }

统一返回结果

// 注册统一返回结果
builder.Services.AddWitchCUnifyResult();

// 在控制器中使用
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        var user = new { Id = id, Name = "张三" };
        return Success(user);  // 自动包装为统一格式
    }

    [HttpGet]
    public IActionResult GetUsers(int pageIndex = 1, int pageSize = 10)
    {
        var users = GetUsersFromDb();
        var total = GetTotalCount();
        return Paged(users, total, pageIndex, pageSize);  // 分页结果
    }
}

// 返回格式
// {
//   "statusCode": 200,
//   "succeeded": true,
//   "message": "success",
//   "data": { "id": 1, "name": "张三" },
//   "traceId": "abc123"
// }

🚀 快速开始

安装

# 从 NuGet 安装核心模块
dotnet add package WitchC

# 安装特定模块
dotnet add package WitchC.ExceptionHandler
dotnet add package WitchC.DynamicApi
dotnet add package WitchC.Jwt
dotnet add package WitchC.Cache
dotnet add package WitchC.Http

基础使用

// Program.cs
using WitchC.ExceptionHandler;
using WitchC.DynamicApi;
using WitchC.Jwt;
using WitchC.Cache;
using WitchC.Cors;
using WitchC.Http;
using WitchC.Localization;
using WitchC.FileStorage;
using WitchC.Logging;
using WitchC.Email;
using WitchC.SignalR;
using WitchC.Schedule;
using WitchC.WorkerService;

var builder = WebApplication.CreateBuilder(args);

// 注册服务
builder.Services.AddWitchCDynamicApi();
builder.Services.AddWitchCMemoryCache();
builder.Services.AddWitchCJwt(options =>
{
    options.SecretKey = "your-secret-key-at-least-32-chars";
    options.Issuer = "MyApp";
});
builder.Services.AddWitchCCors(options =>
{
    options.AllowAnyOrigin = true;
    options.AllowAnyMethod = true;
});
builder.Services.AddWitchCHttp();
builder.Services.AddWitchCLocalization();
builder.Services.AddWitchCFileStorage();
builder.Services.AddWitchCOperationLog();
builder.Services.AddWitchCEmail(options =>
{
    options.SmtpServer = "smtp.example.com";
    options.SmtpPort = 587;
});
builder.Services.AddWitchCSignalR();
builder.Services.AddWitchCSchedule();
builder.Services.AddWitchCWorker();

var app = builder.Build();

// 使用中间件
app.UseGlobalExceptionMiddleware(async (context, result) =>
{
    context.Response.StatusCode = result.StatusCode;
    await context.Response.WriteAsJsonAsync(new
    {
        errorCode = result.ErrorCode,
        message = result.Message
    });
});

app.UseWitchCCors();
app.UseWitchCLocalization();
app.MapWitchCHubs();
app.MapControllers();
app.Run();

📖 模块使用示例

1. 动态 WebAPI

// 定义服务接口
public interface IUserService : IDynamicApiController
{
    Task<UserDto> GetUser(int userId);
    Task<UserDto> CreateUser(CreateUserDto dto);
}

// 实现服务（自动暴露为 /api/user/get-user 等端点）
public class UserService : IUserService
{
    public async Task<UserDto> GetUser(int userId) { ... }
    public async Task<UserDto> CreateUser(CreateUserDto dto) { ... }
}

2. 异常处理

// 使用 Oops 抛出业务异常
throw Oops.Oh("用户不存在");
throw Oops.Oh(ErrorCodes.NotFound);
throw Oops.Oh(ErrorCodes.ValidationError, "用户名");

// 使用 IfException 特性
[IfException(typeof(InvalidOperationException), ErrorCode = "INVALID_OP")]
public IActionResult GetUser(int id) { ... }

3. 数据校验

// 使用 DataValidation 特性
[DataValidation]
public IActionResult CreateUser([FromBody] UserDto dto)
{
    // 自动验证，失败返回 400
    return Ok();
}

// 手动验证
var (isValid, errors) = DataValidation.TryValidate(model);

4. 事件总线

// 定义事件
public class UserCreatedEvent : IEvent
{
    public int UserId { get; set; }
    public string UserName { get; set; }
}

// 事件处理程序（自动注册）
public class UserCreatedEventHandler : IEventHandler<UserCreatedEvent>
{
    public async Task HandleAsync(UserCreatedEvent @event, CancellationToken ct)
    {
        Console.WriteLine($"用户 {@event.UserName} 已创建");
    }
}

// 发布事件
await eventBus.PublishAsync(new UserCreatedEvent { UserId = 1, UserName = "admin" });

5. HTTP 远程请求

// 链式调用
var user = await httpService.Get("https://api.example.com/users/1")
    .WithBearerToken(token)
    .WithTimeout(TimeSpan.FromSeconds(10))
    .SendAsAsync<UserDto>();

// POST 请求
var result = await httpService.Post("https://api.example.com/users")
    .WithJsonBody(new { Name = "张三", Age = 25 })
    .SendAsAsync<CreateResult>();

6. 文件存储

// 上传文件
var result = await fileStorage.UploadAsync(stream, "test.txt", "text/plain");

// 下载文件
using var stream = await fileStorage.DownloadAsync(filePath);

// IFormFile 扩展
var result = await fileStorage.SaveFileAsync(formFile);

// 批量上传
var results = await fileStorage.SaveFilesAsync(formFiles);

7. 多语言

// 获取本地化字符串
var text = localizationService.GetString("Hello", "zh-CN"); // "你好"
var text = localizationService.GetString("Welcome", "en-US", "John"); // "Welcome John"

// 使用 L 静态类
var text = L.Text("Hello");
var text = L.Text("Welcome", "John");

8. 定时任务

// 注册定时任务
builder.Services.AddScheduledTask("cleanup", "0 2 * * *", async ct =>
{
    // 每天凌晨 2 点执行清理
    await CleanupAsync(ct);
});

// 自定义后台服务
public class MyWorker : WitchCBackgroundService
{
    protected override int IntervalSeconds => 60;
    
    protected override async Task ExecuteTaskAsync(CancellationToken ct)
    {
        // 每 60 秒执行一次
    }
}

9. JWT 鉴权

// 生成令牌
var claims = new[]
{
    new Claim(ClaimTypes.NameIdentifier, "1"),
    new Claim(ClaimTypes.Name, "admin")
};
var token = jwtService.GenerateAccessToken(claims);
var refreshToken = jwtService.GenerateRefreshToken();

// 验证令牌
var isValid = jwtService.ValidateToken(token);
var principal = jwtService.GetPrincipalFromToken(token);

10. 邮件发送

// 发送简单邮件
await emailService.SendSimpleAsync("to@example.com", "主题", "正文");

// 发送 HTML 邮件
await emailService.SendSimpleAsync("to@example.com", "主题", "<h1>Hello</h1>", true);

// 发送带附件的邮件
var message = new EmailMessage
{
    To = { "to@example.com" },
    Subject = "带附件的邮件",
    HtmlBody = "<p>请查收附件</p>",
    Attachments = { await EmailAttachment.FromFileAsync("report.pdf") }
};
await emailService.SendAsync(message);

11. 数据脱敏

string phone = Desensitize.Phone("13812345678");     // "138****5678"
string idCard = Desensitize.IdCard("110101199001011234"); // "1101**********1234"
string email = Desensitize.Email("test@example.com"); // "tes***@example.com"
string name = Desensitize.Name("张三");               // "张*"
string bankCard = Desensitize.BankCard("6222021234567890123"); // "6222***********0123"

12. 分布式 ID

// 雪花 ID
long id = IdGenerator.NextSnowflakeId();
string idStr = IdGenerator.NextSnowflakeIdString();

// 有序 GUID
Guid guid = IdGenerator.NextSequentialGuid();

// 带前缀 ID
string orderId = IdGenerator.NextPrefixedId("ORD"); // "ORD000001"
string logId = IdGenerator.NextTimestampId("LOG");   // "LOG20240101120000001"

13. 操作日志

// 使用特性标记
[OperationLog("用户登录", Description = "用户登录系统")]
public IActionResult Login(LoginDto dto) { ... }

// 自动记录：操作人、请求路径、IP、耗时、状态码

📁 项目结构

WitchC/
├── framework/                              # 框架源码
│   ├── WitchC.sln                          # 框架解决方案（22 个项目）
│   ├── Directory.Build.props               # 全局构建属性
│   │
│   ├── WitchC/                             # 核心框架
│   │   ├── App/                            #   App 门面类
│   │   └── Extensions/                     #   10 个扩展方法库
│   │
│   ├── WitchC.ExceptionHandler/            # 异常处理
│   │   ├── Exceptions/                     #   BusinessException, FriendlyException
│   │   ├── Attributes/                     #   IfException, ErrorCodeItemMetadata
│   │   └── ErrorCodes/                     #   错误码枚举
│   │
│   ├── WitchC.DataAnnotations/             # 数据验证
│   │   ├── Attributes/                     #   DataValidation, NonValidation
│   │   ├── Filters/                        #   DataValidationFilter
│   │   └── Results/                        #   ValidationResult
│   │
│   ├── WitchC.DynamicApi/                  # 动态 WebAPI
│   │   ├── Attributes/                     #   ApiSettings, HttpMethodOverride
│   │   ├── Providers/                      #   DynamicApiFeatureProvider
│   │   ├── Selectors/                      #   DynamicApiSelector
│   │   └── Conventions/                    #   DynamicApiConvention
│   │
│   ├── WitchC.DatabaseAccessor.SqlSugar/   # SqlSugar 数据访问
│   │   ├── Repositories/                   #   仓储接口和实现
│   │   ├── Auditing/                       #   审计实体、拦截器
│   │   ├── UnitOfWork/                     #   工作单元
│   │   └── Filters/                        #   软删除筛选器
│   │
│   ├── WitchC.Mapper/                      # 对象映射
│   ├── WitchC.EventBus/                    # 事件总线
│   ├── WitchC.Http/                        # HTTP 请求
│   ├── WitchC.Email/                       # 邮件发送
│   ├── WitchC.Cors/                        # CORS 跨域
│   ├── WitchC.SignalR/                     # 即时通讯
│   ├── WitchC.Jwt/                         # JWT 鉴权
│   ├── WitchC.Encryption/                  # 数据加解密
│   ├── WitchC.Desensitization/             # 数据脱敏
│   ├── WitchC.FileStorage/                 # 文件存储
│   ├── WitchC.IdGeneration/                # 分布式 ID
│   ├── WitchC.Logging/                     # 操作日志
│   ├── WitchC.Schedule/                    # 定时任务
│   ├── WitchC.Localization/                # 多语言
│   ├── WitchC.WorkerService/               # 后台任务
│   ├── WitchC.Cache/                       # 分布式缓存
│   └── WebApplication1/                    # 测试应用
│
├── samples/                                # 示例项目
│   └── witchc-web-api/                     # RBAC 示例（DDD 架构）
│       ├── WitchC.Web.API/                 #   Web API 层
│       ├── WitchC.RBAC.Application/        #   应用层
│       ├── WitchC.RBAC.Domain/             #   领域层
│       ├── WitchC.RBAC.Infrastructure/     #   基础设施层
│       └── WitchC.RBAC.UnitTests/          #   单元测试
│
└── nupkgs/                                 # NuGet 包输出

🔧 技术栈

🧪 测试

# 运行所有测试
dotnet test samples/witchc-web-api/WitchC.RBAC.UnitTests/

# 运行特定测试类
dotnet test --filter "ClassName=EncryptTests"

# 运行特定测试方法
dotnet test --filter "MethodName=Md5_ShouldReturn32CharHash"

测试覆盖

📖 核心概念

1. App 门面类

// 获取配置
var value = App.GetConfig<string>("ConnectionStrings:Default");

// 获取选项
var options = App.GetOptions<JwtOptions>();

// 获取服务
var service = App.GetService<IUserService>();

// 获取当前用户 ID
var userId = App.HttpContext?.GetUserId();

2. 服务注册

// 注册所有模块
builder.Services.AddWitchCDynamicApi();
builder.Services.AddWitchCMemoryCache();
builder.Services.AddWitchCJwt(options => { ... });
builder.Services.AddWitchCCors(options => { ... });
builder.Services.AddWitchCHttp();
builder.Services.AddWitchCSignalR();
builder.Services.AddWitchCSchedule();
builder.Services.AddWitchCLocalization();
builder.Services.AddWitchCFileStorage();
builder.Services.AddWitchCOperationLog();
builder.Services.AddWitchCEmail(options => { ... });
builder.Services.AddWitchCWorker();

3. 中间件配置

// 全局异常处理
app.UseGlobalExceptionMiddleware(async (context, result) => { ... });

// CORS 跨域
app.UseWitchCCors();

// 多语言
app.UseWitchCLocalization();

// SignalR Hub
app.MapWitchCHubs();

🆚 与 Furion 对比

WitchC 已实现的 Furion 模块

🎯 路线图

v1.0.0 (已完成)

• 核心框架搭建
• 21 个功能模块
• 10 个扩展方法库
• 61 个单元测试
• 示例项目（RBAC DDD）

v1.1.0 (规划中)

• 视图/模板引擎
• 工作流引擎
• 分布式事务
• API 网关
• 更多单元测试

v2.0.0 (远景)

• 微服务支持
• 云原生适配
• AI 集成
• 低代码平台

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

📄 许可证

本项目采用 Apache 2.0 许可证 - 查看 LICENSE 文件了解详情

📞 支持与联系

• 🐙 Gitee: https://gitee.com/ingkele/WitchC
• 📧 邮箱: 598792849@qq.com

🙏 致谢

感谢以下开源项目：

• Furion - 设计灵感参考
• SqlSugar - ORM 支持
• Mapster - 对象映射
• MailKit - 邮件发送

╔═══════════════════════════════════════════════════╗
║   感谢使用 WitchC 框架！让我们一起创造魔法！   ║
║   Let's make some magic with .NET! ✨             ║
╚═══════════════════════════════════════════════════╝

最后更新: 2026年6月