Bitzsoft.Integrations.FileStorage.Aliyun 1.0.0-alpha.7

Bitzsoft.Integrations.FileStorage.Aliyun

阿里云 OSS 文件存储实现。

功能特性

• 完整实现 IFileStore 接口：覆盖所有文件与存储桶操作
• 扩展接口 IAliyunOssFileStore：支持带 ACL / 存储类型 / 数据冗余类型的高级存储桶创建
• 预签名 URL：生成带过期时间的下载地址和客户端直传参数（PostObject 签名策略）
• 分片上传：超过 5MB 的文件自动切换为分片上传（Multipart Upload），支持不可寻址流
• 文件元数据：保存文件时支持设置 ContentType 和 ContentDisposition
• 配置提供器模式：通过 IAliyunOssConfigProvider 抽象配置获取，支持静态配置或动态配置中心

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage.Aliyun

PackageReference

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

配置

appsettings.json

{
  "AliyunOss": {
    "Endpoint": "oss-cn-hangzhou.aliyuncs.com",
    "AccessKeyId": "your-access-key-id",
    "AccessKeySecret": "your-access-key-secret",
    "DefaultBucketName": "my-app-bucket",
    "UploadUrlExpiration": 3600,
    "DownloadUrlExpiration": 3600
  }
}

注册服务

使用 DI 扩展方法（推荐）

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

var services = new ServiceCollection();

// 一行注册阿里云 OSS 文件存储服务（内部自动注册处理器工厂、配置提供器、第三方请求日志基础设施）
services.AddBitzsoftAliyunOssFileStorage(options =>
{
    options.Endpoint = "oss-cn-hangzhou.aliyuncs.com";
    options.AccessKeyId = "your-access-key-id";
    options.AccessKeySecret = "your-access-key-secret";
    options.DefaultBucketName = "my-app-bucket";
});

手动注册

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

var services = new ServiceCollection();

// 注册文件名 / 存储桶名称处理器工厂
services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 注册阿里云 OSS 配置
services.AddSingleton<IAliyunOssConfigProvider, AliyunOssConfigProvider>();

// 注册文件存储服务
services.AddSingleton<IAliyunOssFileStore, AliyunFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAliyunOssFileStore>());

从 IConfiguration 绑定配置

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

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();

// 注册处理器工厂
services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 从配置节绑定 AliyunOssOptions
services.AddSingleton<IAliyunOssConfigProvider>(sp =>
{
    var options = configuration.GetSection("AliyunOss").Get<AliyunOssOptions>();
    return new AliyunOssConfigProvider(options);
});

services.AddSingleton<IAliyunOssFileStore, AliyunFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAliyunOssFileStore>());

使用 IOptions 模式

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

var services = new ServiceCollection();

services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 配置选项
services.Configure<AliyunOssOptions>(
    configuration.GetSection("AliyunOss"));

// AliyunOssConfigProvider 内部通过 IOptions<AliyunOssOptions> 获取配置
services.AddSingleton<IAliyunOssConfigProvider, AliyunOssConfigProvider>();
services.AddSingleton<IAliyunOssFileStore, AliyunFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAliyunOssFileStore>());

第三方请求日志

本连接器基于阿里云 OSS SDK，HTTP 管道封装在 SDK 内部，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。请求日志改由 IRequestLogRecorder 回调钩子实现，在对象存储操作包装层记录每次 API 调用，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

每个对象存储操作产生一条日志记录：

由于 SDK 不暴露原始 HTTP 状态码与响应头，StatusCode 无法像 HttpClient 拦截那样记录真实值（成功记 200、异常时留空），也无法记录 RequestHeaders。此外，仅本连接器已实现的对象存储操作会被记录，SDK 的其他能力（如生命周期、跨域、权限策略等）不在记录范围。

// ① 默认：启用回调但不持久化（日志丢弃）
services.AddBitzsoftAliyunOssFileStorage(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，对象存储操作自动落库
//    AddBitzsoftAliyunOssFileStorage 内部已注入 IRequestLogRecorder，宿主无需再额外挂载 handler
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 0;               // 下载响应可能很长，0=不截断完整保留
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
services.AddBitzsoftAliyunOssFileStorage(options => { /* ... */ });

自定义 IRequestLogStore 实现（SqlSugar / Dapper / MongoDB）详见 Bitzsoft.Integrations.RequestLogging。

使用示例

保存文件并获取下载链接

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class ReportService
{
    private readonly IAliyunOssFileStore _fileStore;

    public ReportService(IAliyunOssFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<string> UploadReportAsync(Stream pdfStream, string reportName)
    {
        // 保存 PDF 到默认存储桶
        var result = await _fileStore.SaveFileAsync(
            pdfStream, $"{reportName}.pdf");

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

        return downloadUrl;
    }
}

带元数据保存文件

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class ContractService
{
    private readonly IFileStore _fileStore;

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

    public async Task<FileResult> UploadContractAsync(
        Stream contractStream, string contractId)
    {
        var args = new SaveFileArgs($"{contractId}.pdf", contractStream)
        {
            ContentType = "application/pdf",
            ContentDisposition = $"attachment; filename=\"contract-{contractId}.pdf\""
        };

        return await _fileStore.SaveFileAsync(args);
    }
}

创建带高级配置的存储桶

using Aliyun.OSS;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class TenantProvisioningService
{
    private readonly IAliyunOssFileStore _fileStore;

    public TenantProvisioningService(IAliyunOssFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task CreateTenantBucketAsync(string tenantId)
    {
        var bucketName = $"tenant-{tenantId}";
        var exists = await _fileStore.BucketExistsAsync(bucketName);
        if (exists)
            return;

        // 使用扩展接口创建存储桶，指定访问权限、存储类型和数据冗余
        var args = new CreateBucketArgs(bucketName)
        {
            Acl = CannedAccessControlList.Private,
            StorageClass = StorageClass.Standard,
            DataRedundancyType = DataRedundancyType.LRS
        };

        await _fileStore.CreateBucketAsync(args);
    }
}

生成客户端直传参数

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class UploadService
{
    private readonly IFileStore _fileStore;

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

    /// <summary>
    /// 生成直传参数，供前端通过 PostObject 直接上传到 OSS
    /// </summary>
    public async Task<DirectUploadParam> PrepareDirectUploadAsync(string fileName)
    {
        var args = new GenerateUploadUrlArgs(fileName);
        args.SetOctetStream();

        var uploadParam = await _fileStore.GenerateUploadUrlAsync(args);

        // uploadParam.Url   -> 直传目标地址 (https://bucket.oss-cn-xxx.aliyuncs.com)
        // uploadParam.Data  -> DirectUploadData (Key, Policy, OssAccessKeyId, Signature)
        return uploadParam;
    }
}

从远程 URL 拉取文件到 OSS

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class MediaSyncService
{
    private readonly IFileStore _fileStore;

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

    public async Task<FileResult> SyncExternalImageAsync(string imageUrl, string saveAs)
    {
        var args = new SaveFileByUrlArgs(saveAs, imageUrl)
        {
            BucketName = "media-assets"
        };

        return await _fileStore.SaveFileByUrlAsync(args);
    }
}

复制与移动文件

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aliyun;

public class FileOrganizer
{
    private readonly IFileStore _fileStore;

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

    public async Task ArchiveFileAsync(string sourceFile, string archivePath)
    {
        // 复制文件到归档路径
        await _fileStore.CopyFileAsync(sourceFile, archivePath);

        // 删除原文件（等同于 MoveFileAsync）
        await _fileStore.DeleteFileAsync(sourceFile);
    }

    public async Task MoveToBucketAsync(
        string fileName, string sourceBucket, string destBucket)
    {
        var sourceArgs = new FileStorageArgs(fileName) { BucketName = sourceBucket };
        var destArgs = new FileStorageArgs(fileName) { BucketName = destBucket };

        await _fileStore.MoveFileAsync(sourceArgs, destArgs);
    }
}

核心类型一览

依赖

• Bitzsoft.Integrations.Compatibility，基础工具库
• Bitzsoft.Integrations.FileStorage，多云文件存储抽象层
• Aliyun.OSS.SDK.NetCore，阿里云 OSS 官方 SDK
• aliyun-net-sdk-sts，阿里云 STS SDK
• Microsoft.Extensions.Options，选项模式支持
• Microsoft.Extensions.Http，HttpClient 工厂支持

相关包

• Bitzsoft.Integrations.FileStorage，多云文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Minio，MinIO 文件存储实现
• Bitzsoft.Integrations.FileStorage.Azure，Azure Blob Storage 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aws，AWS S3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Tencent，腾讯云 COS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Huawei，华为云 OBS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Kingsoft，金山云 KS3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Qiniu，七牛云 Kodo 文件存储实现
• Bitzsoft.Integrations.FileStorage.Upyun，又拍云文件存储实现
• Bitzsoft.Integrations.FileStorage.Nas，NAS / 本地文件系统存储实现
• Bitzsoft.Integrations.FileStorage.All，全部云存储实现聚合包