kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fe887c0641
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/file/FileController/0002-upload.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

3.5 KiB
Raw Blame History

统一上传接口

接口信息

  • 接口名称: 统一上传接口
  • 接口路径: /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 实体类存储
  • 上传路径自动生成，包含时间戳避免文件名冲突
  • 支持大文件上传，具体大小限制取决于存储类型配置