通用附件

通用附件系统为所有模块提供统一的文件上传和管理能力。

功能概览

功能	说明
文件上传	统一的文件上传接口
文件下载	按需下载文件内容
业务关联	附件可关联到任意业务实体
元数据	文件名、大小、类型等元信息管理

实体说明

KitFile

文件基础信息。

字段	类型	说明
Id	Guid	主键
FileName	string	文件名
FileSize	long	文件大小
FileType	string	文件类型
FilePath	string	文件路径
Url	string	访问 URL
CreateUserId	Guid	上传者
CreateTime	DateTime	上传时间

KitFileMeta

文件扩展信息。

字段	类型	说明
Id	Guid	主键
FileId	Guid	关联文件
Key	string	元数据键
Value	string	元数据值

CommonAttachment

通用附件关联。

字段	类型	说明
Id	Guid	主键
EntityId	Guid	业务实体 ID
EntityType	string	业务实体类型
FileId	Guid	关联文件
Sort	int	排序

快速开始

1. 配置文件存储

{
  "FileStorage": {
    "MaxFileSize": 83886080,
    "NumLimit": 3,
    "Exclude": ".exe,.dll,.jar",
    "ServiceName": "LocalFileManager",
    "LocalFile": {
      "PrefixPath": "assets",
      "Host": "https://localhost:7002/"
    }
  }
}

2. 上传文件

[ApiController]
[Route("api/[controller]")]
public class FileController : FreeKitController
{
    private readonly IFileManager _fileManager;

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

    [HttpPost("upload")]
    public async Task<FileDto> Upload(IFormFile file)
    {
        var result = await _fileManager.UploadAsync(file);
        return new FileDto
        {
            Id = result.Id,
            Url = result.Url
        };
    }
}

3. 关联附件

[HttpPost("articles/{id}/attachments")]
public async Task AttachToArticle(Guid id, List<Guid> fileIds)
{
    var attachmentService = serviceProvider.GetRequiredService<ICommonAttachmentService>();
    
    foreach (var fileId in fileIds)
    {
        await attachmentService.CreateAsync(new CommonAttachment
        {
            EntityId = id,
            EntityType = "Article",
            FileId = fileId
        });
    }
}

[HttpGet("articles/{id}/attachments")]
public async Task<List<FileDto>> GetArticleAttachments(Guid id)
{
    var attachmentService = serviceProvider.GetRequiredService<ICommonAttachmentService>();
    var attachments = await attachmentService.GetListAsync("Article", id);
    
    return attachments.Select(a => new FileDto
    {
        Id = a.File.Id,
        FileName = a.File.FileName,
        Url = a.File.Url
    }).ToList();
}

API 接口

FileController

方法	路由	说明
POST	/api/file/upload	上传文件
GET	/api/file/{id}	下载文件
DELETE	/api/file/{id}	删除文件

CommonAttachmentController

方法	路由	说明
POST	/api/attachment	创建关联
GET	/api/attachment/{entityType}/{entityId}	获取关联
DELETE	/api/attachment/{id}	删除关联

存储提供器

本地文件存储

services.AddFileManager<LocalFileManager>();

R2 存储

services.AddFileManager<R2FileManager>();

配置选项

{
  "FileStorage": {
    "MaxFileSize": 83886080,
    "NumLimit": 3,
    "Exclude": ".exe,.dll,.jar",
    "ServiceName": "LocalFileManager",
    "LocalFile": {
      "PrefixPath": "assets",
      "Host": "https://localhost:7002/"
    },
    "R2": {
      "AccountId": "your-account-id",
      "AccessKeyId": "your-access-key",
      "SecretAccessKey": "your-secret-key",
      "BucketName": "your-bucket"
    }
  }
}

运维建议

建议	说明
文件大小限制	设置合理的 MaxFileSize
文件类型限制	配置 Exclude 排除危险类型
定期清理	清理无关联的文件
备份	定期备份文件存储

相关文档

• 配置
• R2 存储