414 lines
11 KiB
Markdown
414 lines
11 KiB
Markdown
# 文件模块 API 文档索引
|
||
|
||
> **唯一真源文档**
|
||
>
|
||
> 本文档是文件模块 API 的唯一真源文档，包含所有文件存储和文件信息管理接口的完整说明。
|
||
|
||
## 📋 文档信息
|
||
|
||
- **文档版本**: v1.0.0
|
||
- **创建日期**: 2026-01-18
|
||
- **最后更新**: 2026-01-18
|
||
- **维护者**: Datai Team
|
||
- **文档路径**: `docs/api-docs/file/index.md`
|
||
|
||
## 🎯 概述
|
||
|
||
文件模块提供统一的文件存储服务，支持多种存储类型（local、minio、aliyun-oss），包括文件上传、下载、预览、分片上传等功能。同时提供文件信息管理功能，支持文件信息的查询、导出、新增、修改、删除等操作。
|
||
|
||
## 📚 控制器导航
|
||
|
||
### 1. FileController
|
||
|
||
**文档**: [FileController/](./FileController/)
|
||
|
||
**用途**: 提供统一的文件存储服务接口
|
||
|
||
**功能特点**:
|
||
- 支持多种存储类型（local、minio、aliyun-oss）
|
||
- 提供统一的文件上传、下载、预览接口
|
||
- 支持分片上传，适用于大文件
|
||
- 部分接口支持匿名访问
|
||
|
||
**接口列表**:
|
||
- [0001-client-list.md](./FileController/0001-client-list.md) - 获取所有可用存储渠道及其client列表
|
||
- [0002-upload.md](./FileController/0002-upload.md) - 统一上传接口
|
||
- [0003-download.md](./FileController/0003-download.md) - 统一下载接口
|
||
- [0004-preview.md](./FileController/0004-preview.md) - 统一预览接口（支持匿名访问）
|
||
- [0005-resource.md](./FileController/0005-resource.md) - 本地资源通用下载（支持匿名访问）
|
||
- [0006-init-upload.md](./FileController/0006-init-upload.md) - 初始化分片上传
|
||
- [0007-upload-chunk.md](./FileController/0007-upload-chunk.md) - 上传文件分片
|
||
- [0008-complete-upload.md](./FileController/0008-complete-upload.md) - 完成分片上传并合并文件
|
||
|
||
**使用场景**:
|
||
- 文件上传和下载
|
||
- 文件预览（图片、文档等）
|
||
- 大文件分片上传
|
||
- 本地资源访问
|
||
- 多存储类型支持
|
||
|
||
### 2. SysFileInfoController
|
||
|
||
**文档**: [SysFileInfoController/](./SysFileInfoController/)
|
||
|
||
**用途**: 提供文件信息的管理接口
|
||
|
||
**功能特点**:
|
||
- 支持文件信息的查询、导出、新增、修改、删除
|
||
- 支持分页查询和条件过滤
|
||
- 支持批量删除
|
||
- 所有接口都需要认证和权限控制
|
||
|
||
**接口列表**:
|
||
- [0001-list.md](./SysFileInfoController/0001-list.md) - 查询文件列表
|
||
- [0002-export.md](./SysFileInfoController/0002-export.md) - 导出文件列表
|
||
- [0003-get-info.md](./SysFileInfoController/0003-get-info.md) - 获取文件详细信息
|
||
- [0004-add.md](./SysFileInfoController/0004-add.md) - 新增文件
|
||
- [0005-edit.md](./SysFileInfoController/0005-edit.md) - 修改文件
|
||
- [0006-remove.md](./SysFileInfoController/0006-remove.md) - 删除文件
|
||
|
||
**使用场景**:
|
||
- 文件信息查询和管理
|
||
- 文件列表导出
|
||
- 文件信息维护
|
||
- 批量文件操作
|
||
|
||
## 🔧 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Java 8 或更高版本
|
||
- Spring Boot 2.x 或更高版本
|
||
- 支持的存储类型：
|
||
- local: 本地文件系统
|
||
- minio: MinIO 对象存储
|
||
- aliyun-oss: 阿里云 OSS 对象存储
|
||
|
||
### 依赖配置
|
||
|
||
#### Maven 依赖
|
||
|
||
```xml
|
||
<dependencies>
|
||
<!-- 文件存储模块 -->
|
||
<dependency>
|
||
<groupId>com.datai</groupId>
|
||
<artifactId>datai-file-starter</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
|
||
<!-- MinIO 客户端（可选） -->
|
||
<dependency>
|
||
<groupId>io.minio</groupId>
|
||
<artifactId>minio</artifactId>
|
||
<version>8.5.7</version>
|
||
</dependency>
|
||
|
||
<!-- 阿里云 OSS 客户端（可选） -->
|
||
<dependency>
|
||
<groupId>com.aliyun.oss</groupId>
|
||
<artifactId>aliyun-sdk-oss</artifactId>
|
||
<version>3.17.4</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
#### Gradle 依赖
|
||
|
||
```groovy
|
||
dependencies {
|
||
implementation 'com.datai:datai-file-starter:1.0.0'
|
||
implementation 'io.minio:minio:8.5.7'
|
||
implementation 'com.aliyun.oss:aliyun-sdk-oss:3.17.4'
|
||
}
|
||
```
|
||
|
||
### 配置示例
|
||
|
||
#### application.yml
|
||
|
||
```yaml
|
||
# 文件存储配置
|
||
file:
|
||
# 默认存储类型
|
||
default-storage-type: local
|
||
|
||
# 本地存储配置
|
||
local:
|
||
enabled: true
|
||
base-path: /data/files
|
||
|
||
# MinIO 配置
|
||
minio:
|
||
enabled: true
|
||
endpoint: http://localhost:9000
|
||
access-key: minioadmin
|
||
secret-key: minioadmin
|
||
bucket-name: files
|
||
|
||
# 阿里云 OSS 配置
|
||
aliyun-oss:
|
||
enabled: false
|
||
endpoint: oss-cn-hangzhou.aliyuncs.com
|
||
access-key-id: your-access-key-id
|
||
access-key-secret: your-access-key-secret
|
||
bucket-name: your-bucket-name
|
||
```
|
||
|
||
## 📖 使用指南
|
||
|
||
### 1. 文件上传
|
||
|
||
#### 简单上传
|
||
|
||
```java
|
||
import org.springframework.web.multipart.MultipartFile;
|
||
import org.springframework.beans.factory.annotation.Autowired;
|
||
import com.datai.file.controller.FileController;
|
||
|
||
@RestController
|
||
public class MyController {
|
||
|
||
@Autowired
|
||
private FileController fileController;
|
||
|
||
@PostMapping("/upload")
|
||
public String uploadFile(@RequestParam("file") MultipartFile file) {
|
||
// 使用默认存储类型上传
|
||
String url = fileController.uploadUnified(file);
|
||
return url;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 指定存储类型上传
|
||
|
||
```java
|
||
@PostMapping("/upload")
|
||
public String uploadFile(
|
||
@RequestParam("file") MultipartFile file,
|
||
@RequestParam("storageType") String storageType,
|
||
@RequestParam("bucketName") String bucketName
|
||
) {
|
||
// 指定存储类型和存储桶上传
|
||
String url = fileController.uploadUnified(file, storageType, bucketName);
|
||
return url;
|
||
}
|
||
```
|
||
|
||
### 2. 文件下载
|
||
|
||
```java
|
||
@GetMapping("/download")
|
||
public void downloadFile(
|
||
@RequestParam("storageType") String storageType,
|
||
@RequestParam("bucketName") String bucketName,
|
||
@RequestParam("objectName") String objectName,
|
||
HttpServletResponse response
|
||
) {
|
||
// 下载文件
|
||
fileController.downloadUnified(storageType, bucketName, objectName, response);
|
||
}
|
||
```
|
||
|
||
### 3. 文件预览
|
||
|
||
```java
|
||
@GetMapping("/preview")
|
||
public void previewFile(
|
||
@RequestParam("storageType") String storageType,
|
||
@RequestParam("bucketName") String bucketName,
|
||
@RequestParam("objectName") String objectName,
|
||
HttpServletResponse response
|
||
) {
|
||
// 预览文件
|
||
fileController.preview(storageType, bucketName, objectName, response);
|
||
}
|
||
```
|
||
|
||
### 4. 分片上传
|
||
|
||
#### 初始化分片上传
|
||
|
||
```java
|
||
@PostMapping("/init-multipart-upload")
|
||
public Map<String, Object> initMultipartUpload(
|
||
@RequestParam("fileName") String fileName,
|
||
@RequestParam("fileSize") Long fileSize,
|
||
@RequestParam("chunkSize") Integer chunkSize,
|
||
@RequestParam("storageType") String storageType,
|
||
@RequestParam("bucketName") String bucketName
|
||
) {
|
||
// 初始化分片上传
|
||
return fileController.initMultipartUpload(
|
||
fileName, fileSize, chunkSize, storageType, bucketName
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 上传文件分片
|
||
|
||
```java
|
||
@PostMapping("/upload-chunk")
|
||
public Map<String, Object> uploadChunk(
|
||
@RequestParam("uploadId") String uploadId,
|
||
@RequestParam("chunkNumber") Integer chunkNumber,
|
||
@RequestParam("file") MultipartFile file
|
||
) {
|
||
// 上传文件分片
|
||
return fileController.uploadFileChunk(uploadId, chunkNumber, file);
|
||
}
|
||
```
|
||
|
||
#### 完成分片上传
|
||
|
||
```java
|
||
@PostMapping("/complete-multipart-upload")
|
||
public Map<String, Object> completeMultipartUpload(
|
||
@RequestParam("uploadId") String uploadId
|
||
) {
|
||
// 完成分片上传并合并文件
|
||
return fileController.completeMultipartUpload(uploadId);
|
||
}
|
||
```
|
||
|
||
### 5. 文件信息查询
|
||
|
||
```java
|
||
@Autowired
|
||
private SysFileInfoController fileInfoController;
|
||
|
||
@GetMapping("/file-list")
|
||
public PageResult<SysFileInfo> getFileList(
|
||
@RequestParam(defaultValue = "1") Integer pageNum,
|
||
@RequestParam(defaultValue = "10") Integer pageSize,
|
||
@RequestParam(required = false) String fileName,
|
||
@RequestParam(required = false) String filePath
|
||
) {
|
||
// 查询文件列表
|
||
SysFileInfo fileInfo = new SysFileInfo();
|
||
fileInfo.setFileName(fileName);
|
||
fileInfo.setFilePath(filePath);
|
||
|
||
return fileInfoController.list(pageNum, pageSize, fileInfo);
|
||
}
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 存储类型选择
|
||
|
||
- **local**: 适用于小规模应用，文件存储在本地文件系统
|
||
- **minio**: 适用于需要对象存储功能的应用，支持分布式存储
|
||
- **aliyun-oss**: 适用于需要云存储的应用，提供高可用性和扩展性
|
||
|
||
### 2. 文件大小限制
|
||
|
||
- 单次上传文件大小限制：100 MB（可配置）
|
||
- 分片上传支持大文件：最大 10 GB
|
||
- 分片大小建议：5-10 MB
|
||
|
||
### 3. 安全性
|
||
|
||
- 文件上传需要认证（除匿名接口外）
|
||
- 文件下载和预览需要认证（除匿名接口外）
|
||
- 文件信息管理需要认证和权限控制
|
||
- 支持文件类型白名单和黑名单
|
||
|
||
### 4. 性能优化
|
||
|
||
- 使用分片上传提高大文件上传效率
|
||
- 使用 CDN 加速文件访问
|
||
- 合理设置缓存策略
|
||
- 定期清理过期文件
|
||
|
||
### 5. 错误处理
|
||
|
||
- 文件不存在：返回 404 错误
|
||
- 文件上传失败：返回详细错误信息
|
||
- 存储空间不足：返回 507 错误
|
||
- 权限不足：返回 403 错误
|
||
|
||
## 🎓 最佳实践
|
||
|
||
### 1. 文件命名规范
|
||
|
||
```java
|
||
// 使用时间戳 + 随机数生成唯一文件名
|
||
String fileName = System.currentTimeMillis() + "_" +
|
||
UUID.randomUUID().toString().substring(0, 8) +
|
||
".jpg";
|
||
```
|
||
|
||
### 2. 文件路径组织
|
||
|
||
```java
|
||
// 按日期组织文件路径
|
||
String filePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
|
||
```
|
||
|
||
### 3. 文件类型验证
|
||
|
||
```java
|
||
// 验证文件类型
|
||
String[] allowedTypes = {"image/jpeg", "image/png", "application/pdf"};
|
||
if (!Arrays.asList(allowedTypes).contains(file.getContentType())) {
|
||
throw new IllegalArgumentException("不支持的文件类型");
|
||
}
|
||
```
|
||
|
||
### 4. 文件大小验证
|
||
|
||
```java
|
||
// 验证文件大小
|
||
long maxSize = 100 * 1024 * 1024; // 100 MB
|
||
if (file.getSize() > maxSize) {
|
||
throw new IllegalArgumentException("文件大小超过限制");
|
||
}
|
||
```
|
||
|
||
### 5. 异常处理
|
||
|
||
```java
|
||
try {
|
||
String url = fileController.uploadUnified(file);
|
||
return url;
|
||
} catch (Exception e) {
|
||
log.error("文件上传失败", e);
|
||
throw new RuntimeException("文件上传失败: " + e.getMessage());
|
||
}
|
||
```
|
||
|
||
## 🔗 相关资源
|
||
|
||
### 官方文档
|
||
|
||
- [Spring Boot 文件上传](https://spring.io/guides/gs/uploading-files/)
|
||
- [MinIO 文档](https://docs.min.io/)
|
||
- [阿里云 OSS 文档](https://help.aliyun.com/product/31815.html)
|
||
|
||
### 相关模块
|
||
|
||
- [datai-scene-file](../../../datai-scenes/datai-scene-file/) - 文件存储模块源代码
|
||
- [Authentication.canvas](../../Authentication.canvas) - 项目架构图
|
||
|
||
## 📝 更新日志
|
||
|
||
### v1.0.0 (2026-01-18)
|
||
|
||
- 初始版本发布
|
||
- 包含 FileController 和 SysFileInfoController 的完整 API 文档
|
||
- 提供使用示例和最佳实践
|
||
- 添加注意事项和错误处理指南
|
||
|
||
## 📧 联系方式
|
||
|
||
如有问题或建议，请联系：
|
||
- **维护者**: Datai Team
|
||
- **邮箱**: support@datai.com
|
||
- **文档路径**: `docs/api-docs/file/index.md`
|
||
|
||
---
|
||
|
||
**注意**: 本文档是唯一真源文档，所有关于文件模块 API 的使用说明和最佳实践都应以此文档为准。如有任何疑问，请参考本文档或联系维护者。
|