kris/datai

Fork 0

Kris 3d290a8dd1 feat：归档当前所有文件

2026-01-28 18:23:25 +08:00

11 KiB

Raw Permalink Blame History

文件模块 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/

用途: 提供统一的文件存储服务接口

功能特点:

支持多种存储类型（local、minio、aliyun-oss）
提供统一的文件上传、下载、预览接口
支持分片上传，适用于大文件
部分接口支持匿名访问

接口列表:

0001-client-list.md - 获取所有可用存储渠道及其client列表
0002-upload.md - 统一上传接口
0003-download.md - 统一下载接口
0004-preview.md - 统一预览接口（支持匿名访问）
0005-resource.md - 本地资源通用下载（支持匿名访问）
0006-init-upload.md - 初始化分片上传
0007-upload-chunk.md - 上传文件分片
0008-complete-upload.md - 完成分片上传并合并文件

使用场景:

文件上传和下载
文件预览（图片、文档等）
大文件分片上传
本地资源访问
多存储类型支持

2. SysFileInfoController

文档: SysFileInfoController/

用途: 提供文件信息的管理接口

功能特点:

支持文件信息的查询、导出、新增、修改、删除
支持分页查询和条件过滤
支持批量删除
所有接口都需要认证和权限控制

接口列表:

0001-list.md - 查询文件列表
0002-export.md - 导出文件列表
0003-get-info.md - 获取文件详细信息
0004-add.md - 新增文件
0005-edit.md - 修改文件
0006-remove.md - 删除文件

使用场景:

文件信息查询和管理
文件列表导出
文件信息维护
批量文件操作

🔧 快速开始

环境要求

Java 8 或更高版本
Spring Boot 2.x 或更高版本
支持的存储类型：
- local: 本地文件系统
- minio: MinIO 对象存储
- aliyun-oss: 阿里云 OSS 对象存储

依赖配置

Maven 依赖

<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 依赖

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

# 文件存储配置
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. 文件上传

简单上传

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;
    }
}

指定存储类型上传

@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. 文件下载

@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. 文件预览

@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. 分片上传

初始化分片上传

@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
    );
}

上传文件分片

@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);
}

完成分片上传

@PostMapping("/complete-multipart-upload")
public Map<String, Object> completeMultipartUpload(
    @RequestParam("uploadId") String uploadId
) {
    // 完成分片上传并合并文件
    return fileController.completeMultipartUpload(uploadId);
}

5. 文件信息查询

@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. 文件命名规范

// 使用时间戳 + 随机数生成唯一文件名
String fileName = System.currentTimeMillis() + "_" + 
                  UUID.randomUUID().toString().substring(0, 8) + 
                  ".jpg";

2. 文件路径组织

// 按日期组织文件路径
String filePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));

3. 文件类型验证

// 验证文件类型
String[] allowedTypes = {"image/jpeg", "image/png", "application/pdf"};
if (!Arrays.asList(allowedTypes).contains(file.getContentType())) {
    throw new IllegalArgumentException("不支持的文件类型");
}

4. 文件大小验证

// 验证文件大小
long maxSize = 100 * 1024 * 1024; // 100 MB
if (file.getSize() > maxSize) {
    throw new IllegalArgumentException("文件大小超过限制");
}

5. 异常处理

try {
    String url = fileController.uploadUnified(file);
    return url;
} catch (Exception e) {
    log.error("文件上传失败", e);
    throw new RuntimeException("文件上传失败: " + e.getMessage());
}

🔗 相关资源

官方文档

📝 更新日志

v1.0.0 (2026-01-18)

初始版本发布
包含 FileController 和 SysFileInfoController 的完整 API 文档
提供使用示例和最佳实践
添加注意事项和错误处理指南

📧 联系方式

如有问题或建议，请联系：

维护者: Datai Team
邮箱: support@datai.com
文档路径: docs/api-docs/file/index.md

注意: 本文档是唯一真源文档，所有关于文件模块 API 的使用说明和最佳实践都应以此文档为准。如有任何疑问，请参考本文档或联系维护者。

11 KiB Raw Permalink Blame History Unescape Escape