datai/docs/archive/api-docs/file/FileController/index.md

FileController 接口文档

概述

FileController 提供统一的文件存储服务接口，支持多种存储类型（local、minio、aliyun-oss 等），包括文件上传、下载、预览、分片上传等功能。

接口列表

基础接口

接口名称	接口路径	请求方法	说明
获取所有可用存储渠道及其client列表	/file/client-list	GET	获取系统可用的存储渠道列表
统一上传接口	/file/upload /file/{storageType}/{bucketName}/upload	POST	上传文件到指定存储
统一下载接口	/file/download /file/{storageType}/{bucketName}/download	GET	从指定存储下载文件
统一预览接口	/file/preview /file/{storageType}/{bucketName}/preview	GET	在线预览文件（支持匿名访问）
本地资源通用下载	/file/resource	GET	下载本地资源文件（支持匿名访问）

分片上传接口

接口名称	接口路径	请求方法	说明
初始化分片上传	/file/initUpload	POST	初始化分片上传，获取 uploadId
上传文件分片	/file/uploadChunk	POST	上传文件的一个分片
完成分片上传并合并文件	/file/completeUpload	POST	完成分片上传并合并文件

存储类型

系统支持以下存储类型：

• local: 本地文件系统存储
• minio: MinIO 对象存储
• aliyun-oss: 阿里云 OSS 对象存储

使用流程

普通文件上传流程

1. 调用 获取存储渠道列表 获取可用的存储渠道
2. 调用 统一上传接口 上传文件
3. 使用返回的 URL 进行文件访问

分片上传流程

1. 调用 初始化分片上传 获取 uploadId 和文件路径
2. 循环调用 上传文件分片 上传所有分片
3. 调用 完成分片上传 合并所有分片

文件下载流程

1. 调用 统一下载接口 下载文件
2. 浏览器会自动触发文件下载

文件预览流程

1. 调用 统一预览接口 预览文件
2. 浏览器会根据文件类型进行在线预览

权限说明

• 大部分接口需要认证（需要携带 Authorization 头）
• 统一预览接口 和 本地资源通用下载 支持匿名访问

注意事项

1. 文件路径格式为：upload/{timestamp}_{originalFilename}
2. 分片上传适用于大文件（通常大于 100MB）
3. 分片序号必须从 1 开始，连续递增
4. 需要妥善保存 uploadId 和所有分片的 ETag
5. 预览接口会自动识别文件类型

相关文档

• SysFileInfoController 接口文档 - 文件信息管理接口