# 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)