64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
# 8.5 文件上传接口
|
||
|
||
:::tip 概述
|
||
上传接口执行两段式的第一段（落临时目录）：multipart 提交文件，返回临时访问 URL；该 URL 随业务表单提交，保存记录时由后端转正。
|
||
:::
|
||
|
||
## 接口清单
|
||
|
||
| 方法 | 路径 | 权限码 | 说明 |
|
||
|---|---|---|---|
|
||
| POST | /api/upload/uploadFile | sys:upload:file | 单文件上传 |
|
||
| POST | /api/upload/uploadFiles | sys:upload:files | 批量上传 |
|
||
|
||
## 请求
|
||
|
||
```text
|
||
Content-Type: multipart/form-data
|
||
file: 二进制文件（单文件字段名 file）
|
||
type: 可选，"image" 走图片白名单+内容嗅探，其余按通用文件白名单（internal/model/dto/upload.go UploadFileReq）
|
||
```
|
||
|
||
大小与扩展名受服务端配置约束（file.maxSize / imageExt / fileExt），超限返回失败信封。批量接口字段名为 `files`（min=1）。
|
||
|
||
## 响应
|
||
|
||
单文件（UploadFileRes）：
|
||
|
||
```json
|
||
{
|
||
"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 转正，它们只是中间值，不是最终文件地址。
|
||
|
||
## 完整时序
|
||
|
||
```text
|
||
① POST /api/upload/uploadFile（multipart）→ data.url（temp）
|
||
② 业务表单携带该 url 提交（如新增文章的 cover 字段）
|
||
③ 后端 Add → ModuleSpec saveTransform → 转正到 {模块目录}/{yyyymmdd}/
|
||
④ 入库为转正后的相对路径；读侧补域名返回完整 URL
|
||
```
|
||
|
||
## 前端使用
|
||
|
||
公共 Upload 组件已封装此流程；手写调用时注意：**上传成功≠文件可用**，必须随表单保存后才算落库。
|
||
|
||
## 相关
|
||
|
||
- [7.1 文件上传全流程](/zh/tools/upload.html)
|
||
- [7.2 上传配置详解](/zh/tools/upload-config.html)
|