# 文件模块 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 的使用说明和最佳实践都应以此文档为准。如有任何疑问，请参考本文档或联系维护者。