BugFree.FileStorage 1.0.2026.107-beta1426

FileStorage 模块说明

组成

• BugFree.FileStorage：封装文件存储抽象（IFileStorage/IBucketStorage）、动态提供者选择（FileStorageService），内置阿里云 OSS、腾讯云 COS、本地文件系统实现。
• BugFree.Controllers.FileStorage：对外 REST 控制器，区域默认 Oss，包含配置读取与文件操作接口，支持事件回调（FileStorageEventHandler）。

支持能力

• Bucket（可选）：存在性检查、创建、删除（接口 IBucketStorage）。
• Object（核心）：上传（流/路径）、下载（流/路径）、删除、判断存在、生成访问 URL（签名）、复制。
• 元信息：FileMetadata 模型可按需扩展（暂未暴露在控制器）。

配置

配置模型 FileStorageSetting（Config<FileStorageSetting>，支持加密存储）：

{
  "Provider": "AliCloud | TencentCloud | Local | None",
  "AliCloud": {
    "Region": "cn-hangzhou",
    "Endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
    "BucketName": "your-bucket",
    "AccessKeyId": "<YOUR_KEY>",
    "AccessKeySecret": "<YOUR_SECRET>"
  },
  "TencentCloud": {
    "AppId": "<APPID>",
    "Region": "ap-guangzhou",
    "SecretId": "<SECRET_ID>",
    "SecretKey": "<SECRET_KEY>",
    "BucketName": "your-bucket-123456",
    "Url": "https://your-bucket-123456.cos.ap-guangzhou.myqcloud.com"
  },
  "Local": {
    "RootPath": "./files",
    "AccessUrl": "http://localhost:5000/",
    "ParamEncryptKey": "<RANDOM_KEY>"
  }
}

依赖注入

• 服务注册：services.AddFileStorageService();
• 控制器事件注册：services.AddFileStorage(new FileStorageEventHandler { /* 订阅事件 */ });
• FileStorageService 根据 FileStorageSetting.Current.Provider 惰性创建具体实现。

事件回调（可选）

通过 FileStorageEventHandler 订阅以下事件，控制器在操作成功后调用：

• Uploaded(bucket, key)
• Presigned(bucket, key, url)
• Deleted(bucket, key)
• ExistsChecked(bucket, key, exists)
• Copied(sourceBucket, sourceKey, destBucket, destKey)

控制器接口（默认路由示例）

• POST /Oss/v1/FileStorage/Upload?bucket=&key=：上传文件（表单 file）。
• GET /Oss/v1/FileStorage/Presign?bucket=&key=&minutes=5：生成临时访问地址。
• DELETE /Oss/v1/FileStorage/Delete?bucket=&key=：删除对象。
• GET /Oss/v1/FileStorage/Exists?bucket=&key=：判断对象是否存在。
• POST /Oss/v1/FileStorage/Copy?sourceBucket=&sourceKey=&destBucket=&destKey=：复制对象。
• GET /Oss/v1/Setting/Get：读取当前 FileStorageSetting（继承自 ConfigControllerBase 标准路由）。

本地存储说明

• RootPath 为空时回退当前目录，按 bucket/key 组织文件。
• AccessUrl 必填用于生成可访问 URL；ParamEncryptKey 用于对访问参数加密（对称加密算法随机择取）。

使用示例

// 注册
services.AddFileStorageService();
services.AddFileStorage(new FileStorageEventHandler
{
    Uploaded = (bucket, key) => new ValueTask(Task.CompletedTask)
});

// 服务侧上传
await _fileStorageService.Upload("demo", "path/demo.txt", stream);
var url = await _fileStorageService.GeneratePresignedUrl("demo", "path/demo.txt", TimeSpan.FromMinutes(10));

注意事项

• SDK 调用结果异常会抛出，调用方需处理（网络/权限/配置）。
• 若当前 Provider 不支持 Bucket 操作会抛出 NotSupportedException。
• 不要提交真实密钥，示例中请替换占位符。