datai/docs/archive/api-docs/file/FileController/0002-upload.md

统一上传接口

接口信息

• 接口名称: 统一上传接口
• 接口路径: /file/upload 或 /file/{storageType}/{bucketName}/upload
• 请求方法: POST
• 模块归属: file
• 版本号: v1.0.0
• 创建日期: 2026-01-18
• 最后更新: 2026-01-18

功能描述

提供统一的文件上传接口，支持指定存储类型和存储桶，也可以使用默认存储。上传成功后返回文件访问 URL 和文件信息。

请求参数

路径参数

参数名	类型	必填	描述	示例
storageType	String	否	存储类型，不传则使用默认存储	minio, local, aliyun-oss
bucketName	String	否	存储桶名称，不传则使用默认存储桶	primary, backup

表单参数

参数名	类型	必填	描述	示例
file	MultipartFile	是	要上传的文件	-

响应数据

成功响应

HTTP 状态码: 200 OK

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "url": "https://example.com/files/upload/1234567890_test.jpg",
    "info": {
      "fileId": 1,
      "fileName": "test.jpg",
      "filePath": "upload/1234567890_test.jpg",
      "fileSize": 102400,
      "fileType": "jpg",
      "storageType": "minio",
      "createTime": "2026-01-18T10:00:00"
    },
    "fileName": "test.jpg"
  }
}

字段名	类型	描述	示例
url	String	文件访问 URL	https://example.com/files/upload/1234567890_test.jpg
info	Object	文件详细信息对象	-
fileName	String	文件名	test.jpg

失败响应

HTTP 状态码: 500 Internal Server Error

{
  "code": 500,
  "message": "上传失败: 存储空间不足",
  "data": null
}

接口示例

请求示例

使用默认存储:

curl -X POST "http://localhost:8080/file/upload" \
  -H "Authorization: Bearer [token]" \
  -F "file=@/path/to/file.jpg"

指定存储类型和存储桶:

curl -X POST "http://localhost:8080/file/minio/primary/upload" \
  -H "Authorization: Bearer [token]" \
  -F "file=@/path/to/file.jpg"

响应示例

成功:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "url": "https://minio.example.com/files/upload/1234567890_test.jpg",
    "info": {
      "fileId": 1,
      "fileName": "test.jpg",
      "filePath": "upload/1234567890_test.jpg",
      "fileSize": 102400,
      "fileType": "jpg",
      "storageType": "minio",
      "createTime": "2026-01-18T10:00:00"
    },
    "fileName": "test.jpg"
  }
}

错误处理

• 文件为空时返回错误
• 存储空间不足时返回错误
• 存储类型或存储桶不存在时返回错误
• 文件大小超过限制时返回错误

注意事项

• 文件路径格式为：upload/{timestamp}_{originalFilename}
• 上传成功后会自动在数据库中创建文件记录
• 支持多种存储类型：local、minio、aliyun-oss 等
• 不指定存储类型时使用系统配置的默认存储

相关接口

• 获取存储渠道列表 - 获取可用的存储渠道
• 统一下载接口 - 下载已上传的文件
• 统一预览接口 - 预览已上传的文件

实现细节

• 使用 StorageService 处理文件上传
• 文件信息使用 SysFileInfo 实体类存储
• 上传路径自动生成，包含时间戳避免文件名冲突
• 支持大文件上传，具体大小限制取决于存储类型配置