跳到主要内容

Nebula Storage 接口信息

本文档说明 nebula-storage 当前对外暴露的核心接口。接口说明基于：

  • StorageController
  • IStorageService
  • command / query / dto 定义

说明约定：

  • 大多数管理类接口返回统一 ApiResult
  • 分页接口统一使用 POST
  • 文件上传接口使用 multipart/form-data
  • 普通上传完成后仍需调用 bind 才会生成正式文件

1. 创建上传任务​

创建上传任务

仅用于分块上传场景。前端传文件名、文件大小和分块信息即可，文件扩展名由后端根据文件名推导，MIME 类型不在建任务阶段传递。
POST/api/storage/upload-tasks

2. 直接上传单文件​

直接上传单文件

适用于普通附件场景。上传成功后返回临时上传任务详情，后续仍需要 bind 才会生成正式文件。simple 上传不接受 taskId 和 fileMimeType，文件扩展名与 MIME 类型都由后端根据最终文件名推导。
POST/api/storage/upload

3. 上传分片​

上传分片

向指定上传任务写入一个分片，支持可选 partHash 做一致性校验；只要调用方传入 partHash，服务端就会在本次上传时校验它必须与实际分片内容 MD5 一致。
PUT/api/storage/upload-tasks/{taskId}/parts/{partNo}

5. 完成上传任务​

完成上传任务

用于 chunk 场景，触发分片完整性校验、分片合并和临时完整文件生成。
POST/api/storage/upload-tasks/{taskId}/complete

6. 绑定上传任务​

绑定上传任务

把已完成的临时上传任务绑定到业务实体，生成正式文件记录并返回 fileId。
POST/api/storage/upload-tasks/{taskId}/bind

7. 上传任务详情​

上传任务详情

查询上传任务当前状态、上传统计信息和是否已经生成正式文件。
GET/api/storage/upload-tasks/{taskId}

8. 分页查询临时文件​

分页查询临时文件

按任务类型、文件名、任务状态、上传人等条件分页查询临时文件（即上传任务记录）。适合后台查看 simple / chunk 上传过程中的临时文件与任务状态。
POST/api/storage/upload-tasks/page

9. 正式文件详情​

正式文件详情

查询正式文件元数据与业务归属信息。
GET/api/storage/files/{fileId}

10. 分页查询正式文件​

分页查询正式文件

按文件名、业务来源、上传人等条件分页查询正式文件。
POST/api/storage/files/page

10. 登录态鉴权下载​

登录态鉴权下载

前端或已登录调用方通过 Authorization 下载正式文件。
GET/api/storage/download

11. 生成签名下载地址​

生成签名下载地址

登录态用户在通过原始下载权限校验后，生成一个可分享给第三方的短时签名下载地址。
POST/api/storage/generate-signed-url

12. 签名下载正式文件​

签名下载正式文件

第三方或未登录用户通过分享链接下载文件，不依赖 Authorization，只依赖签名、时效和次数限制。
GET/api/storage/download-signed

13. 删除正式文件​

删除正式文件

删除正式文件记录；如果没有其他记录引用同一底层存储位置，模块会进一步删除真实内容。
DELETE/api/storage/files/{fileId}

14. 接口使用建议​

14.1 普通附件​

推荐顺序：

  1. POST /api/storage/upload
  2. POST /api/storage/upload-tasks/{taskId}/bind
  3. GET /api/storage/files/{fileId} 或 /api/storage/download

14.2 大文件​

推荐顺序：

  1. POST /api/storage/upload-tasks
  2. PUT /api/storage/upload-tasks/{taskId}/parts/{partNo}
  3. POST /api/storage/upload-tasks/{taskId}/complete
  4. POST /api/storage/upload-tasks/{taskId}/bind

14.3 分享下载​

推荐顺序：

  1. POST /api/storage/generate-signed-url
  2. 把返回的 data.url 分享给第三方
  3. 第三方访问 /api/storage/download-signed