NestJS Boilerplate 文件上传功能详解

NestJS Boilerplate 文件上传功能详解

前言

在现代Web应用中，文件上传是一个常见且重要的功能。本文将深入解析NestJS Boilerplate项目中提供的文件上传解决方案，帮助开发者理解其架构设计和使用方法。

文件上传驱动支持

NestJS Boilerplate提供了三种开箱即用的文件存储驱动：

1. 本地存储(local) - 文件直接存储在服务器本地文件系统
2. S3存储(s3) - 文件上传到AWS S3云存储
3. S3预签名URL(s3-presigned) - 通过预签名URL直接上传到S3

开发者可以通过修改环境变量FILE_DRIVER来切换不同的存储驱动。对于生产环境，推荐使用"s3-presigned"驱动，因为它能减轻服务器负载。

本地存储驱动实现

上传流程

本地存储是最简单的实现方式，适合开发和测试环境：

1. 前端通过POST请求发送文件到/api/v1/files/upload端点
2. 后端接收文件并存储在指定目录
3. 后端返回包含文件ID和路径的File实体
4. 前端可以将此File实体关联到其他业务实体

示例：用户头像上传

sequenceDiagram
    participant 前端应用
    participant 后端服务
    
    前端应用->>后端服务: POST /api/v1/files/upload (包含文件数据)
    后端服务->>前端应用: 返回File实体(id, path)
    前端应用->>后端服务: PATCH /api/v1/auth/me (关联文件到用户)

AWS S3存储驱动实现

配置步骤

1. 创建S3存储桶
2. 配置CORS策略允许跨域请求
3. 设置环境变量：

   FILE_DRIVER=s3
   ACCESS_KEY_ID=您的访问密钥
   SECRET_ACCESS_KEY=您的密钥
   AWS_S3_REGION=区域
   AWS_DEFAULT_S3_BUCKET=存储桶名称
   

上传流程

1. 前端上传文件到后端API
2. 后端将文件转发到S3存储
3. 返回文件信息供前端关联

S3预签名URL实现

这是生产环境推荐的方式，可以减轻服务器负担。

配置要点

1. 存储桶CORS配置需要允许PUT方法
2. 生产环境应限制允许的来源域名
3. 环境变量配置与普通S3驱动类似，但驱动类型设为s3-presigned

上传流程

sequenceDiagram
    participant 前端应用
    participant 后端服务
    participant AWS S3
    
    前端应用->>后端服务: 发送文件名(不含文件内容)
    后端服务->>前端应用: 返回预签名URL和File实体
    前端应用->>AWS S3: 直接使用URL上传文件
    前端应用->>后端服务: 关联文件到用户

文件删除策略

项目默认采用"软删除"策略，不实际删除文件，主要基于以下考虑：

1. 便于数据恢复
2. 避免意外删除导致的用户体验问题
3. 与数据库的软删除策略保持一致

如需实现文件删除功能，开发者可以自行扩展处理逻辑或创建定时任务。

最佳实践建议

1. 开发环境：使用local驱动简化配置
2. 生产环境：优先考虑s3-presigned驱动
3. 安全配置：
   • 限制上传文件类型和大小
   • 生产环境CORS应指定具体域名
   • 使用IAM角色最小权限原则
4. 性能优化：
   • 对大文件考虑分片上传
   • 实现上传进度显示
   • 考虑CDN加速文件访问

总结

NestJS Boilerplate提供了灵活的文件上传解决方案，支持多种存储后端，开发者可以根据实际需求选择合适的实现方式。理解这些不同的上传机制及其适用场景，有助于构建更健壮、高效的Web应用。