2.1 KiB
2.1 KiB
8.5 文件上传接口
:::tip 概述 上传接口执行两段式的第一段（落临时目录）：multipart 提交文件，返回临时访问 URL；该 URL 随业务表单提交，保存记录时由后端转正。 :::
接口清单
| 方法 | 路径 | 权限码 | 说明 |
|---|---|---|---|
| POST | /api/upload/uploadFile | sys:upload:file | 单文件上传 |
| POST | /api/upload/uploadFiles | sys:upload:files | 批量上传 |
请求
Content-Type: multipart/form-data
file: 二进制文件（单文件字段名 file）
type: 可选，"image" 走图片白名单+内容嗅探，其余按通用文件白名单（internal/model/dto/upload.go UploadFileReq）
大小与扩展名受服务端配置约束（file.maxSize / imageExt / fileExt），超限返回失败信封。批量接口字段名为 files（min=1）。
响应
单文件（UploadFileRes）：
{
"code": 0, "ok": true, "msg": "操作成功",
"data": {
"originalName": "原始文件名.png",
"fileExtension": "png",
"fileType": "image/png",
"fileSize": 10240,
"fileName": "ab12cd....png",
"filePath": "temp/20261025/ab12cd....png",
"fileUrl": "http://file.example.com/temp/20261025/ab12cd....png"
}
}
批量（UploadFilesRes）：{ "list": [UploadFileRes, ...] }。
注意 filePath/fileUrl 指向的仍是 temp 临时路径形态——表单提交保存记录时才经 saveTransform 转正，它们只是中间值，不是最终文件地址。
完整时序
① POST /api/upload/uploadFile（multipart）→ data.url（temp）
② 业务表单携带该 url 提交（如新增文章的 cover 字段）
③ 后端 Add → ModuleSpec saveTransform → 转正到 {模块目录}/{yyyymmdd}/
④ 入库为转正后的相对路径；读侧补域名返回完整 URL
前端使用
公共 Upload 组件已封装此流程；手写调用时注意：上传成功≠文件可用，必须随表单保存后才算落库。