跳到主要内容
版本：3.0.0

文件管理（Aegis.FileManager）

Aegis.FileManager 提供文件管理抽象和文件校验能力。它本身不绑定具体存储，更多承担“统一接口 + 校验规则”的基础层角色。

组件概览​

字段说明
组件名称文件管理
真实类库Aegis.FileManager
组件定位文件上传下载抽象与文件校验基础层
引入方式安装 NuGet 后，通过服务注册启用
核心能力IFileManager 抽象、文件大小与扩展名校验、自定义检查器
典型配套NAS 文件存储（Aegis.FileManager.Nas）、S3 文件存储（Aegis.FileManager.S3）

什么时候要用它​

适合场景：

  • 你要统一文件上传、下载、删除的业务入口
  • 你要在上传前做大小限制和扩展名校验
  • 你要把文件管理能力和具体存储实现解耦

最小接入方式​

第一步：启用文件校验​

builder.Services.AddFileValidation(options =>
{
    options.EnableValidation = true;
    options.StrictExtensionCheck = true;
    options.FileSizeLimit[FileType.Image] = 10 * 1024 * 1024;
    options.FileSizeLimit[FileType.Pdf] = 20 * 1024 * 1024;
});

第二步：注册实际存储实现​

Aegis.FileManager 只提供抽象层，业务里真正要注入 IFileManager 时，还需要同时注册具体实现，例如 NAS 文件存储 或 S3 文件存储。

默认校验项​

启用 AddFileValidation(...) 后，默认会带上两类校验：

  • 文件大小限制
  • 文件扩展名检查

对应配置模型是 FileCheckOptions：

{
  "FileValidation": {
    "EnableValidation": true,
    "StrictExtensionCheck": true
  }
}

业务中怎么用​

业务层最常见的写法是注入 IFileManager：

public class AttachmentService
{
    private readonly IFileManager _fileManager;

    public AttachmentService(IFileManager fileManager)
    {
        _fileManager = fileManager;
    }

    public bool Upload(Stream stream, string fileName)
    {
        return _fileManager.UploadFile(fileName, stream, FileType.File, "attachments");
    }

    public byte[] Download(string fileName)
    {
        return _fileManager.GetFileBytes(fileName, "attachments");
    }
}

自定义校验器怎么加​

如果默认大小和扩展名规则不够，可以继续追加自己的 IFileChecker。

public class PdfSignatureChecker : IFileChecker
{
    public Exception DoCheck(Stream stream, FileType type)
    {
        if (type != FileType.Pdf)
        {
            return null;
        }

        var buffer = new byte[4];
        stream.Read(buffer, 0, 4);
        var isPdf = buffer[0] == 0x25 && buffer[1] == 0x50 && buffer[2] == 0x44 && buffer[3] == 0x46;

        return isPdf ? null : new Exception("PDF 文件头不正确");
    }
}

builder.Services.AddFileChecker<PdfSignatureChecker>();

接入后怎么确认生效​

通常用下面几项验收：

  • 大小超限文件会被拦住
  • 扩展名不匹配的文件会被拦住
  • 注入 IFileManager 的业务类可以正常上传、读取和删除文件

常见问题​

只有 AddFileValidation(...)，但注入 IFileManager 仍然失败​

这是因为你只启用了抽象层和校验层，还没有注册具体存储实现。通常还要再接入一个实际文件管理器，例如 NAS 文件存储 或 S3 文件存储。

上传接口总是报扩展名错误​

优先检查：

  • 上传时传入的 FileType 是否正确
  • StrictExtensionCheck 是否开启
  • 文件名和实际内容是否匹配