cq_anquan
/
safety-eval-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
safety-eval-service/docs/文件上传接口文档.md

8.0 KiB
Raw Blame History

文件上传接口文档

目录

接口概览

类别 方法 路径 说明
上传 POST /file/upload 内部单个上传
上传 POST /file/upload/batch 内部批量上传
管理 GET /file-storage/presigned-url/{fileId} 获取签名 URL
管理 GET /file-storage/info/{fileId} 获取文件信息
管理 GET /file-storage/download/{fileId} 下载文件
管理 GET /file-storage/list-all 全部文件列表
管理 GET /file-storage/list-by-creator 按上传者查询
管理 DELETE /file-storage/delete/{fileId} 删除文件
管理 DELETE /file-storage/delete-batch 批量删除

通用说明

基础路径

开发环境: http://localhost:{port}
生产环境: 按实际部署域名

统一响应体

{
  "success": true,
  "code": "0",
  "message": "ok",
  "data": { ... }
}

文件上传大小限制

限制项 值
单文件上限 100 MB
单次请求上限 500 MB

支持文件类型

不限制文件类型，支持文本、图片、音频、视频等所有常见格式。

上传接口（内部）

所有上传接口均为内部接口，需要携带有效登录凭证（Cookie / Token）。
上传完成后自动将文件元信息写入 filestorage 表。

1. 内部单个上传

POST /file/upload

请求

参数 类型 必填 说明
file MultipartFile (form-data) 是 上传的文件

示例

curl -X POST "http://localhost:8080/file/upload" \
  -H "Cookie: ..." \
  -F "file=@/path/to/document.pdf"

成功响应

{
  "success": true,
  "code": "0",
  "message": "ok",
  "data": {
    "id": 1001,
    "url": "https://test-dragon-yf-pub.oss-cn-hangzhou.aliyuncs.com/jjb/xxx.pdf",
    "presignedUrl": null,
    "size": 204800,
    "originalFilename": "document.pdf",
    "ext": "pdf",
    "contentType": "application/pdf",
    "creatorName": "张三",
    "createdTime": "2026-06-30T10:30:00"
  }
}
响应字段 类型 说明
id Integer 文件记录主键，后续管理操作依赖此 ID
url String OSS 文件永久访问路径
presignedUrl String 上传时返回 null，需通过签名 URL 接口获取
size Long 文件大小（字节）
originalFilename String 上传时的原始文件名
ext String 文件扩展名
contentType String MIME 类型
creatorName String 创建人姓名（当前登录用户）
createdTime String 文件创建时间

2. 内部批量上传

POST /file/upload/batch

请求

参数 类型 必填 说明
files List<MultipartFile> (form-data) 是 多个上传文件（同名参数）

示例

curl -X POST "http://localhost:8080/file/upload/batch" \
  -H "Cookie: ..." \
  -F "files=@/path/to/file1.png" \
  -F "files=@/path/to/file2.png" \
  -F "files=@/path/to/file3.png"

成功响应

{
  "success": true,
  "code": "0",
  "message": "ok",
  "data": [
    { "id": 1001, "url": "...", "size": 204800, "originalFilename": "file1.png", ... },
    { "id": 1002, "url": "...", "size": 307200, "originalFilename": "file2.png", ... }
  ]
}

部分成功策略：批量上传时，若某个文件上传失败，该文件被跳过，不影响其余文件的上传。

文件管理接口

3. 获取签名 URL

GET /file-storage/presigned-url/{fileId}

返回带 1 小时有效期的临时访问链接，用于文件预览或安全分发。

成功响应

{
  "success": true,
  "data": {
    "id": 1001,
    "url": "https://test-dragon-yf-pub.oss-cn-hangzhou.aliyuncs.com/jjb/xxx.pdf",
    "presignedUrl": "https://test-dragon-yf-pub.oss-cn-hangzhou.aliyuncs.com/jjb/xxx.pdf?Expires=...&OSSAccessKeyId=...&Signature=...",
    "size": 204800,
    "originalFilename": "document.pdf",
    "contentType": "application/pdf",
    "creatorName": "张三",
    "createdTime": "2026-06-30T10:30:00"
  }
}

4. 获取文件信息

GET /file-storage/info/{fileId}

仅返回文件元信息，不主动生成签名 URL。

5. 下载文件

GET /file-storage/download/{fileId}

以附件形式流式下载文件，Content-Disposition: attachment。

6. 删除文件

DELETE /file-storage/delete/{fileId}

同时删除 OSS 文件与 filestorage 表记录，不可恢复。

7. 批量删除

DELETE /file-storage/delete-batch
Content-Type: application/json

[1001, 1002, 1003]

8. 列表查询

接口 说明
GET /file-storage/list-all 查询所有文件记录
GET /file-storage/list-by-creator?creatorUid=xxx 按上传者 UID 查询

内外部调用规则

核心原则

维度 说明
上传写入 必须通过上传接口，由接口自动同步到 filestorage 表
表管理 filestorage 表仅提供读取和删除，不允许直接通过 API 新增/修改记录
安全性 文件不直接暴露 OSS 原始 URL，前端通过签名 URL 获取临时访问权限

调用流程图

┌─────────────┐     POST /file/upload      ┌─────────────┐
│   前端 /    │ ──────────────────────────▶  │  API 层      │
│   调用方    │                              │              │
└─────────────┘                              └──────┬──────┘
                                                    │
                              ┌─────────────────────┼─────────────────────┐
                              ▼                     ▼                     ▼
                       ┌──────────┐         ┌──────────┐         ┌──────────┐
                       │ 上传 OSS  │         │ 写表同步  │         │  获取 ID  │
                       │(x-file-  │         │filestorage│         │ 返回前端  │
                       │ storage) │         │  表记录    │         │          │
                       └──────────┘         └──────────┘         └──────────┘

创建人区分（扩展预留）

当前所有上传接口均为内部接口，创建人取自当前登录用户。扩展场景说明：

场景 接口路径 创建人 适用情况
内部用户上传 /file/upload 当前登录用户 业务操作中上传附件、素材等
> 公开/匿名通道 /file/upload/public system 未登录用户提交（可在需要时暴露）

使用规范

  1. 禁止绕过上传接口直接操作表：filestorage 表的新增只能由上传接口内部完成，外部系统不允许直接 INSERT
  2. 文件访问走签名 URL：presignedUrl 有效期 1 小时，到期后需重新获取
  3. 删除不可逆：删除操作同时清理 OSS 和 DB，调用前需做二次确认

错误码

错误码 说明
03-01-001 文件上传失败
03-01-002 上传文件为空
03-01-003 文件不存在
03-01-004 文件删除失败
03-01-005 文件下载失败
03-01-006 OSS 操作异常
03-01-007 文件地址生成失败
03-01-008 文件大小超出限制