8.5 文件上传接口

概述

上传接口执行两段式的第一段（落临时目录）：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 组件已封装此流程；手写调用时注意：上传成功≠文件可用，必须随表单保存后才算落库。

相关

• 7.1 文件上传全流程
• 7.2 上传配置详解