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

Bitzsoft.Integrations.FileStorage.Aws

AWS S3 文件存储实现。

功能特性

• 完整实现 IFileStore 接口：覆盖所有文件与存储桶操作
• 扩展接口 IAwsS3FileStore：AWS S3 文件存储服务标识接口，支持未来扩展
• 预签名 URL：生成带过期时间的下载地址和上传地址
• 存储桶管理：创建、删除、判断存储桶是否存在
• 文件元数据：保存文件时支持设置 ContentType
• 配置提供器模式：通过 IAwsS3ConfigProvider 抽象配置获取，支持静态配置或动态配置中心
• S3 兼容服务支持：通过 ServiceURL 和 ForcePathStyle 配置可对接 MinIO 等兼容服务
• IHttpClientFactory 集成：通过 Microsoft.Extensions.Http 管理 HTTP 连接

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage.Aws

PackageReference

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

配置

appsettings.json

{
  "AwsS3": {
    "AccessKeyId": "your-access-key-id",
    "SecretAccessKey": "your-secret-access-key",
    "Region": "us-east-1",
    "DefaultBucketName": "my-app-bucket",
    "ServiceURL": null,
    "ForcePathStyle": false,
    "HttpClientName": "FileStorage",
    "UploadUrlExpiration": 3600,
    "DownloadUrlExpiration": 43200
  }
}

注册服务

使用 DI 扩展方法（推荐）

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

var services = new ServiceCollection();

// 注册 HttpClient 工厂
services.AddHttpClient("FileStorage");

// 一行注册 AWS S3 文件存储服务
services.AddBitzsoftAwsS3FileStorage(options =>
{
    options.AccessKeyId = "your-access-key-id";
    options.SecretAccessKey = "your-secret-access-key";
    options.Region = "us-east-1";
    options.DefaultBucketName = "my-app-bucket";
});

从 IConfiguration 绑定配置

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

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

var services = new ServiceCollection();

// 注册 HttpClient 工厂（AwsS3FileStore 通过 IHttpClientFactory 创建 HTTP 客户端）
services.AddHttpClient("FileStorage");

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

// 从配置节绑定 AwsS3Options
services.AddSingleton<IAwsS3ConfigProvider>(sp =>
{
    var options = configuration.GetSection("AwsS3").Get<AwsS3Options>();
    return new AwsS3ConfigProvider(options);
});

services.AddSingleton<IAwsS3FileStore, AwsS3FileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAwsS3FileStore>());

使用 IOptions 模式

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

var services = new ServiceCollection();

services.AddHttpClient("FileStorage");

services.AddSingleton<IFileNameProcessorFactory, FileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, BucketNameProcessorFactory>();

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

// AwsS3ConfigProvider 内部通过 IOptions<AwsS3Options> 获取配置
services.AddSingleton<IAwsS3ConfigProvider, AwsS3ConfigProvider>();
services.AddSingleton<IAwsS3FileStore, AwsS3FileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAwsS3FileStore>());

第三方请求日志

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

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

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

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

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

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

使用示例

保存文件并获取下载链接

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aws;

public class ReportService
{
    private readonly IAwsS3FileStore _fileStore;

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

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

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

        return downloadUrl;
    }
}

通过 IFileStore 抽象使用

using Bitzsoft.Integrations.FileStorage;

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"
        };

        return await _fileStore.SaveFileAsync(args);
    }
}

从远程 URL 拉取文件到 S3

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Aws;

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.Aws;

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，多云文件存储抽象层
• AWSSDK.S3，AWS SDK for .NET（S3 模块）
• Microsoft.Extensions.Http，HttpClient 工厂支持

相关包

• Bitzsoft.Integrations.FileStorage，多云文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Minio，MinIO 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aliyun，阿里云 OSS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Azure，Azure Blob Storage 文件存储实现
• 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，全部云存储实现聚合包