Bitzsoft.Integrations.FileStorage 1.0.0-alpha.5

Bitzsoft.Integrations.FileStorage

多云文件存储抽象层 -- 统一接口定义与基础模型。

功能特性

• 统一的文件存储接口 IFileStore：屏蔽底层云厂商差异，提供一致的 Bucket 和 File 操作 API
• 存储桶管理：获取列表、判断存在、创建、删除
• 文件操作：判断存在、读取流、保存（支持 Stream / FileInfo / byte[]）、URL 远程拉取保存、复制、移动、删除
• 预签名 URL：生成带过期时间的下载 / 上传地址，支持客户端直传
• 文件名与存储桶名称处理策略：通过 IFileNameProcessor / IBucketNameProcessor 实现自定义命名策略（如按日期归档、哈希去重等）
• 文件类型检测：IFileExtensionInspector 基于文件签名（Magic Number）识别扩展名，判断是否为图片 / PDF / 视频
• 文件大小工具：FileSize 结构体提供 Byte / KB / MB / GB 多级单位换算与友好描述
• 参数对象模式：所有操作均提供简单签名（fileName + policy）与 Args 对象签名两套重载，灵活应对简单与复杂场景

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage

PackageReference

<PackageReference Include="Bitzsoft.Integrations.FileStorage" Version="1.0.0" />

配置

本包为抽象层，不直接包含云厂商配置。具体配置由各实现包定义（如 Aliyun、Azure、Aws）。

若需自定义文件名 / 存储桶名称处理策略，可实现 IFileNameProcessorFactory 与 IBucketNameProcessorFactory 并注册到 DI 容器。

配置中心支持

所有实现包的配置读取均基于 IConfiguration → IOptions<T> 标准管道，天然支持任何配置来源，包括但不限于：

• appsettings.json 本地文件
• 环境变量
• AgileConfig、Apollo、Nacos、Consul 等配置中心

各实现包提供的 DI 扩展方法（如 AddBitzsoftMinioFileStorage）内部通过 services.Configure<T>() 绑定配置，配置中心推送的更新会在应用重启后生效。若需运行时热更新，可实现自定义 IXxxConfigProvider，在 GetConfigAsync() 中对接配置中心的监听机制。

注册服务

本包仅定义接口与模型，不提供 AddXxx 扩展方法。请使用具体实现包完成注册：

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 注册文件名 / 存储桶名称处理器工厂（需自行实现）
services.AddSingleton<IFileNameProcessorFactory, CustomFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, CustomBucketNameProcessorFactory>();

// 注册阿里云 OSS 实现（需要 Aliyun 实现包）
services.AddSingleton<IAliyunOssConfigProvider, AliyunOssConfigProvider>();
services.AddSingleton<IFileStore, AliyunFileStore>();

使用示例

保存文件并生成下载链接

using Bitzsoft.Integrations.FileStorage;

public class InvoiceService
{
    private readonly IFileStore _fileStore;

    public InvoiceService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<string> UploadInvoiceAsync(Stream pdfStream, string fileName)
    {
        // 保存文件到默认存储桶
        var result = await _fileStore.SaveFileAsync(pdfStream, fileName);

        // 输出文件信息
        Console.WriteLine($"文件路径: {result.FilePath}");
        Console.WriteLine($"文件大小: {result.Size}");       // 自动选择合适单位
        Console.WriteLine($"扩展名: {result.Extension}");
        Console.WriteLine($"存储桶: {result.Bucket}");

        // 生成 1 小时有效的下载链接
        var downloadUrl = await _fileStore.GenerateDownloadUrlAsync(result.FilePath);
        return downloadUrl;
    }
}

使用 byte[] 扩展方法保存文件

using Bitzsoft.Integrations.FileStorage;

public class AvatarService
{
    private readonly IFileStore _fileStore;

    public AvatarService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> SaveAvatarAsync(byte[] imageBytes, string originalFileName)
    {
        // 使用扩展方法直接保存 byte[]
        return await _fileStore.SaveFileAsync(imageBytes, originalFileName);
    }
}

使用 FileInfo 扩展方法保存本地文件

using System.IO;
using Bitzsoft.Integrations.FileStorage;

public class BackupService
{
    private readonly IFileStore _fileStore;

    public BackupService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> BackupLocalFileAsync(string localPath)
    {
        var fileInfo = new FileInfo(localPath);
        return await _fileStore.SaveFileAsync(fileInfo);
    }
}

从远程 URL 下载并保存到存储

using Bitzsoft.Integrations.FileStorage;

public class ExternalResourceService
{
    private readonly IFileStore _fileStore;

    public ExternalResourceService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> DownloadAndSaveAsync(string fileUrl, string saveAs)
    {
        return await _fileStore.SaveFileByUrlAsync(fileUrl, saveAs);
    }
}

存储桶管理

using Bitzsoft.Integrations.FileStorage;

public class BucketManager
{
    private readonly IFileStore _fileStore;

    public BucketManager(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task EnsureBucketExistsAsync(string bucketName)
    {
        var exists = await _fileStore.BucketExistsAsync(bucketName);
        if (!exists)
        {
            await _fileStore.CreateBucketAsync(bucketName);
        }
    }

    public async Task<List<string>> ListAllBucketsAsync()
    {
        return await _fileStore.GetBucketNamesAsync();
    }
}

文件类型检测

using Bitzsoft.Integrations.FileStorage;

public class FileValidationService
{
    private readonly IFileExtensionInspector _inspector;

    public FileValidationService(IFileExtensionInspector inspector)
    {
        _inspector = inspector;
    }

    public string ValidateUpload(Stream fileStream)
    {
        var extension = _inspector.GetExtension(fileStream);

        if (_inspector.IsImage(fileStream))
            return "图片文件";
        if (_inspector.IsPdf(fileStream))
            return "PDF 文件";
        if (_inspector.IsVideo(fileStream))
            return "视频文件";

        return $"其他文件 (.{extension})";
    }
}

使用 Args 对象进行高级操作

using Bitzsoft.Integrations.FileStorage;

public class AdvancedFileService
{
    private readonly IFileStore _fileStore;

    public AdvancedFileService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task SaveWithMetadataAsync(
        Stream stream, string fileName, string bucketName, string contentType)
    {
        var args = new SaveFileArgs(fileName, stream)
        {
            BucketName = bucketName,
            ContentType = contentType,
            ContentDisposition = $"attachment; filename=\"{fileName}\""
        };

        var result = await _fileStore.SaveFileAsync(args);
    }

    public async Task<string> GenerateDownloadUrlAsync(
        string fileName, string bucketName, string responseContentType)
    {
        var args = new GenerateDownloadUrlArgs(fileName)
        {
            BucketName = bucketName,
            ResponseContentType = responseContentType
        };

        return await _fileStore.GenerateDownloadUrlAsync(args);
    }
}

文件大小单位换算

using Bitzsoft.Integrations.FileStorage;

public class FileSizeExample
{
    public void Demonstrate()
    {
        var size = new FileSize(1536 * 1024 * 1024); // 1536 MB

        Console.WriteLine(size.GetSizeByK());  // 1572864.00
        Console.WriteLine(size.GetSizeByM());  // 1536.00
        Console.WriteLine(size.GetSizeByG());  // 1.50
        Console.WriteLine(size);               // "1.50 GB"

        // 从 MB 构造
        var fromMb = new FileSize(100, FileSizeUnit.M);
        Console.WriteLine(fromMb.GetSizeByM());  // 100.00
    }
}

核心类型一览

依赖

• Bitzsoft.Integrations.Compatibility -- 基础工具库

相关包

• Bitzsoft.Integrations.FileStorage -- 文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Aliyun -- 阿里云 OSS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Azure -- Azure Blob Storage 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aws -- AWS S3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Huawei -- 华为云 OBS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Qiniu -- 七牛云 Kodo 文件存储实现
• Bitzsoft.Integrations.FileStorage.Upyun -- 又拍云文件存储实现
• Bitzsoft.Integrations.FileStorage.Kingsoft -- 金山云 KS3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Nas -- NAS / 本地文件系统存储实现
• Bitzsoft.Integrations.FileStorage.Minio -- MinIO 文件存储实现
• Bitzsoft.Integrations.FileStorage.Tencent -- 腾讯云 COS 文件存储实现
• Bitzsoft.Integrations.FileStorage.All -- 文件存储聚合包
• Bitzsoft.Integrations.Compatibility -- 基础工具库