文件上传¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/api-standards/biz-api/file.md

PubFileUploadController：本地存储文件上传接口。继承标准 CRUD（pub_file_upload 表），另有 5 个自定义接口。

📖 标准 CRUD 接口格式见标准CRUD接口规范。

⚠️ 易错点¶

uploadFile 返回原始 Map，不是 JsonResult
bizType 注释写"默认 file"，代码实际默认 "files"

一、配置信息¶

项	值
物理目录	`/opt/data/fileupload/`
访问前缀	`/bams-apex/egystatics`
单文件限制	10MB
单请求限制	50MB

@Tag：1101-本地存储-文件上传接口。前缀 /file/fileUpload。

PubFileUpload 实体关键字段：file_name（文件名）、file_type（扩展名）、file_high/file_wide（图片高宽）、biz_id/biz_type（业务关联）、version（版本号）、server_path（服务器路径）、order_num、corp_code、deleted

二、POST `/file/fileUpload/uploadFile` — 文件上传（核心）¶

multipart 上传到本地磁盘 + 落库。行为规则：

参数组合	行为
`fileId` 有值	修改已有记录
`isRename=N`（默认）	按"同名文件"匹配已有记录新插一条；存 `{path}/{bizType}/{version}/`；zip 自动解压到目标目录和 `{bizType}/last/`（仅 zip）
`isRename=Y`	文件名改为雪花 ID，存 `{path}/{bizType}/{yyyyMMdd}/`
`isCover=Y`	覆盖存 `{path}/{bizType}/`，沿用原文件名
`isTable=N`	只存盘不落库
记录有旧 serverPath	删除旧物理文件

版本号自动 +0.1（1.0→1.1，HALF_UP 保留 1 位小数）
createdBy/updatedBy 硬编码 "admin"

请求参数（multipart form）¶

参数	必填	说明
`file`	✅	MultipartFile
`fileId`	❌	已有记录 ID（有则修改）
`bizType`	❌	业务类型/子目录，默认 "files"
`bizId`	❌	业务单据主键（Long）
`isRename`	❌	Y/N 改名为雪花 ID，默认 N
`isCover`	❌	Y/N 覆盖模式，默认 N
`isTable`	❌	Y/N 是否落库，默认 Y
`fileHigh` / `fileWide`	❌	图片高/宽（Double）

响应（⚠️ 直接返回 Map，非 JsonResult）¶

{
  "id": "记录ID",
  "src": "/bams-apex/egystatics/files/1.0/xx.xlsx",
  "accessPath": "所在目录"
}

调用示例¶

const formData = new FormData();
formData.append('file', file);
formData.append('bizType', 'contract');
formData.append('bizId', '12345');
const res = await axios.post('/apex-api/file/fileUpload/uploadFile', formData);
// res.data.src → 直接可用的访问 URL

三、其他接口¶

GET `/file/fileUpload/getFileBase64?id={id}` — 读文件为 Base64¶

按记录 ID 读磁盘文件转 Base64。

响应：JsonResult<Object>，data = {src: "data:image/{ext};base64,...", id, accessPath}

GET `/file/fileUpload/deleteFile?fileId={id}` — 删除文件（记录+物理文件）¶

响应：JsonResult<Object>

GET `/file/fileUpload/deleteFileByServerPath?serverPath={path}` — 仅删物理文件¶

不动数据库记录。serverPath 为空返回 fail。

响应：JsonResult<Object>（成功 data=物理路径）

POST `/file/fileUpload/pageList` — 分页查文件记录¶

请求：BasicParamWrapper
响应：JsonResult<Object>（Page）

相关文档¶