文件上传接口

文件上传相关的 API 接口，支持多种上传方式、文件类型和存储策略。

📤 基础上传接口

单文件上传

接口地址：POST /api/upload

请求头：

Authorization: Bearer <jwt-token>
Content-Type: multipart/form-data

请求参数：

参数名	类型	必填	说明
file	file	是	上传的文件
storageType	string	否	存储类型（LOCAL/ALIYUN/TENCENT）
category	string	否	文件分类
description	string	否	文件描述

请求示例：

bash

curl -X POST "http://localhost:8080/api/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/image.jpg" \
  -F "storageType=LOCAL" \
  -F "category=avatar" \
  -F "description=用户头像"

响应示例：

json

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "filename": "image_20240115103000.jpg",
    "originalName": "image.jpg",
    "fileSize": 102400,
    "fileType": "image/jpeg",
    "storageType": "LOCAL",
    "url": "http://localhost:8080/uploads/image_20240115103000.jpg",
    "thumbnailUrl": "http://localhost:8080/uploads/thumbnails/image_20240115103000.jpg",
    "uploadTime": "2024-01-15T10:30:00Z",
    "uploader": {
      "id": 1,
      "username": "admin"
    }
  }
}

多文件上传

接口地址：POST /api/upload/multiple

请求参数：

参数名	类型	必填	说明
files	file[]	是	多个文件
storageType	string	否	存储类型
category	string	否	文件分类

响应示例：

json

{
  "code": 200,
  "message": "上传成功",
  "data": [
    {
      "id": 1,
      "filename": "image1.jpg",
      "originalName": "image1.jpg",
      "url": "http://localhost:8080/uploads/image1.jpg",
      "status": "SUCCESS"
    },
    {
      "id": 2,
      "filename": "image2.jpg",
      "originalName": "image2.jpg",
      "url": "http://localhost:8080/uploads/image2.jpg",
      "status": "SUCCESS"
    }
  ]
}

🔄 分块上传接口

适用于大文件上传，支持断点续传。

初始化分块上传

接口地址：POST /api/upload/chunk/init

请求参数：

参数名	类型	必填	说明
filename	string	是	文件名
fileSize	integer	是	文件大小（字节）
chunkSize	integer	是	分块大小（字节）
totalChunks	integer	是	总分块数

响应示例：

json

{
  "code": 200,
  "message": "初始化成功",
  "data": {
    "uploadId": "upload_123456",
    "chunkSize": 1048576,
    "totalChunks": 10
  }
}

上传分块

接口地址：POST /api/upload/chunk/upload

请求参数：

参数名	类型	必填	说明
uploadId	string	是	上传会话 ID
chunkNumber	integer	是	分块序号（从1开始）
file	file	是	分块文件

响应示例：

json

{
  "code": 200,
  "message": "分块上传成功",
  "data": {
    "chunkNumber": 1,
    "uploadedChunks": [1],
    "progress": "10%"
  }
}

完成分块上传

接口地址：POST /api/upload/chunk/complete

请求参数：

参数名	类型	必填	说明
uploadId	string	是	上传会话 ID
filename	string	是	最终文件名

响应示例：

json

{
  "code": 200,
  "message": "文件上传完成",
  "data": {
    "id": 1,
    "filename": "large_file.zip",
    "url": "http://localhost:8080/uploads/large_file.zip",
    "fileSize": 10485760
  }
}

🌐 URL 上传接口

支持从网络 URL 直接上传文件。

URL 上传

接口地址：POST /api/upload/url

请求参数：

参数名	类型	必填	说明
url	string	是	文件 URL
filename	string	否	自定义文件名
storageType	string	否	存储类型

请求示例：

json

{
  "url": "https://example.com/image.jpg",
  "filename": "downloaded_image.jpg",
  "storageType": "LOCAL"
}

📁 文件管理接口

获取文件信息

接口地址：GET /api/upload/{id}

路径参数：

参数名	类型	必填	说明
id	integer	是	文件 ID

响应示例：

json

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "filename": "image.jpg",
    "originalName": "image.jpg",
    "fileSize": 102400,
    "fileType": "image/jpeg",
    "storageType": "LOCAL",
    "url": "http://localhost:8080/uploads/image.jpg",
    "thumbnailUrl": "http://localhost:8080/uploads/thumbnails/image.jpg",
    "uploadTime": "2024-01-15T10:30:00Z",
    "uploader": {
      "id": 1,
      "username": "admin"
    },
    "metadata": {
      "width": 1920,
      "height": 1080,
      "duration": null
    }
  }
}

删除文件

接口地址：DELETE /api/upload/{id}

路径参数：

参数名	类型	必填	说明
id	integer	是	文件 ID

批量删除文件

接口地址：DELETE /api/upload/batch

请求参数：

json

{
  "ids": [1, 2, 3]
}

🖼️ 图片处理接口

生成缩略图

接口地址：GET /api/upload/{id}/thumbnail

查询参数：

参数名	类型	必填	说明
width	integer	否	宽度（默认200）
height	integer	否	高度（默认200）
quality	integer	否	质量（1-100，默认80）

响应：直接返回缩略图二进制流

图片信息获取

接口地址：GET /api/upload/{id}/info

响应示例：

json

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "width": 1920,
    "height": 1080,
    "format": "JPEG",
    "colorSpace": "sRGB",
    "hasAlpha": false,
    "orientation": 1,
    "fileSize": 102400,
    "exif": {
      "camera": "Canon EOS 5D Mark IV",
      "lens": "EF 24-70mm f/2.8L II USM",
      "iso": 100,
      "shutterSpeed": "1/125",
      "aperture": "f/2.8",
      "focalLength": "50mm"
    }
  }
}

📊 上传统计接口

获取上传统计

接口地址：GET /api/upload/stats

响应示例：

json

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalFiles": 1500,
    "totalSize": 1572864000,
    "todayUploads": 25,
    "todaySize": 26214400,
    "storageDistribution": {
      "LOCAL": 800,
      "ALIYUN": 500,
      "TENCENT": 200
    },
    "fileTypeDistribution": {
      "image/jpeg": 800,
      "image/png": 400,
      "application/pdf": 200,
      "other": 100
    }
  }
}

🔧 配置相关接口

获取上传配置

接口地址：GET /api/upload/config

响应示例：

json

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "maxFileSize": 104857600,
    "allowedTypes": ["image/jpeg", "image/png", "image/gif", "application/pdf"],
    "chunkSize": 1048576,
    "maxChunks": 100,
    "storageTypes": ["LOCAL", "ALIYUN", "TENCENT"],
    "thumbnailSizes": ["200x200", "400x400", "800x800"]
  }
}

⚠️ 错误码说明

错误码	说明	可能原因
2001	文件大小超过限制	文件大于配置的最大大小
2002	文件类型不支持	文件类型不在允许列表中
2003	存储空间不足	用户存储配额已满
2004	上传失败	网络或服务器错误
2005	分块上传失败	分块校验失败
2006	文件已存在	相同文件已上传
2007	URL 下载失败	网络连接问题

🧪 测试示例

基础文件上传

bash

# 单文件上传
curl -X POST "http://localhost:8080/api/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@test.jpg" \
  -F "category=test"

# 多文件上传
curl -X POST "http://localhost:8080/api/upload/multiple" \
  -H "Authorization: Bearer <token>" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg"

分块上传示例

bash

# 1. 初始化分块上传
curl -X POST "http://localhost:8080/api/upload/chunk/init" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "large_file.zip",
    "fileSize": 10485760,
    "chunkSize": 1048576,
    "totalChunks": 10
  }'

# 2. 上传分块（示例：上传第1块）
curl -X POST "http://localhost:8080/api/upload/chunk/upload" \
  -H "Authorization: Bearer <token>" \
  -F "uploadId=<upload-id>" \
  -F "chunkNumber=1" \
  -F "file=@chunk1.bin"

# 3. 完成上传
curl -X POST "http://localhost:8080/api/upload/chunk/complete" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "<upload-id>",
    "filename": "large_file.zip"
  }'

🔄 更新日志

v1.0.0 (2024-01-01)

基础文件上传接口
多文件上传支持
分块上传（断点续传）
URL 上传功能
文件管理接口
图片处理功能
上传统计信息

🔗 相关链接： API 概览

文件上传接口 ​

📤 基础上传接口 ​

单文件上传 ​

多文件上传 ​

🔄 分块上传接口 ​

初始化分块上传 ​

上传分块 ​

完成分块上传 ​

🌐 URL 上传接口 ​

URL 上传 ​

📁 文件管理接口 ​

获取文件信息 ​

删除文件 ​

批量删除文件 ​

🖼️ 图片处理接口 ​

生成缩略图 ​

图片信息获取 ​

📊 上传统计接口 ​

获取上传统计 ​

🔧 配置相关接口 ​

获取上传配置 ​

⚠️ 错误码说明 ​

🧪 测试示例 ​

基础文件上传 ​

分块上传示例 ​

🔄 更新日志 ​

v1.0.0 (2024-01-01) ​

文件上传接口

📤 基础上传接口

单文件上传

多文件上传

🔄 分块上传接口

初始化分块上传

上传分块

完成分块上传

🌐 URL 上传接口

URL 上传

📁 文件管理接口

获取文件信息

删除文件

批量删除文件

🖼️ 图片处理接口

生成缩略图

图片信息获取

📊 上传统计接口

获取上传统计

🔧 配置相关接口

获取上传配置

⚠️ 错误码说明

🧪 测试示例

基础文件上传

分块上传示例

🔄 更新日志

v1.0.0 (2024-01-01)