File Upload API

File upload related API interfaces, supporting multiple upload methods, file types, and storage strategies.

📤 Basic Upload APIs

Single File Upload

Endpoint: POST /api/upload

Request Headers:

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

Request Parameters:

Parameter	Type	Required	Description
file	file	Yes	File to upload
storageType	string	No	Storage type (LOCAL/ALIYUN/TENCENT)
category	string	No	File category
description	string	No	File description

Request Example:

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=User avatar"

Response Example:

json

{
  "code": 200,
  "message": "Upload successful",
  "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"
    }
  }
}

Multiple Files Upload

Endpoint: POST /api/upload/multiple

Request Parameters:

Parameter	Type	Required	Description
files	file[]	Yes	Multiple files
storageType	string	No	Storage type
category	string	No	File category

Response Example:

json

{
  "code": 200,
  "message": "Upload successful",
  "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"
    }
  ]
}

🔄 Chunked Upload APIs

Suitable for large file uploads, supports resumable uploads.

Initialize Chunked Upload

Endpoint: POST /api/upload/chunk/init

Request Parameters:

Parameter	Type	Required	Description
filename	string	Yes	File name
fileSize	integer	Yes	File size (bytes)
chunkSize	integer	Yes	Chunk size (bytes)
totalChunks	integer	Yes	Total number of chunks

Response Example:

json

{
  "code": 200,
  "message": "Initialization successful",
  "data": {
    "uploadId": "upload_123456",
    "chunkSize": 1048576,
    "totalChunks": 10
  }
}

Upload Chunk

Endpoint: POST /api/upload/chunk/upload

Request Parameters:

Parameter	Type	Required	Description
uploadId	string	Yes	Upload session ID
chunkNumber	integer	Yes	Chunk number (starting from 1)
file	file	Yes	Chunk file

Response Example:

json

{
  "code": 200,
  "message": "Chunk upload successful",
  "data": {
    "chunkNumber": 1,
    "uploadedChunks": [1],
    "progress": "10%"
  }
}

Complete Chunked Upload

Endpoint: POST /api/upload/chunk/complete

Request Parameters:

Parameter	Type	Required	Description
uploadId	string	Yes	Upload session ID
filename	string	Yes	Final file name

Response Example:

json

{
  "code": 200,
  "message": "File upload completed",
  "data": {
    "id": 1,
    "filename": "large_file.zip",
    "url": "http://localhost:8080/uploads/large_file.zip",
    "fileSize": 10485760
  }
}

🌐 URL Upload APIs

Support direct file upload from network URLs.

URL Upload

Endpoint: POST /api/upload/url

Request Parameters:

Parameter	Type	Required	Description
url	string	Yes	File URL
filename	string	No	Custom file name
storageType	string	No	Storage type

Request Example:

json

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

📁 File Management APIs

Get File Information

Endpoint: GET /api/upload/{id}

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	File ID

Response Example:

json

{
  "code": 200,
  "message": "Retrieved successfully",
  "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 File

Endpoint: DELETE /api/upload/{id}

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	File ID

Batch Delete Files

Endpoint: DELETE /api/upload/batch

Request Parameters:

json

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

🖼️ Image Processing APIs

Generate Thumbnail

Endpoint: GET /api/upload/{id}/thumbnail

Query Parameters:

Parameter	Type	Required	Description
width	integer	No	Width (default: 200)
height	integer	No	Height (default: 200)
quality	integer	No	Quality (1-100, default: 80)

Response: Returns thumbnail binary stream directly

Get Image Information

Endpoint: GET /api/upload/{id}/info

Response Example:

json

{
  "code": 200,
  "message": "Retrieved successfully",
  "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"
    }
  }
}

📊 Upload Statistics APIs

Get Upload Statistics

Endpoint: GET /api/upload/stats

Response Example:

json

{
  "code": 200,
  "message": "Retrieved successfully",
  "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
    }
  }
}

🔧 Configuration APIs

Get Upload Configuration

Endpoint: GET /api/upload/config

Response Example:

json

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

⚠️ Error Codes

Error Code	Description	Possible Causes
2001	File size exceeds limit	File larger than configured maximum size
2002	File type not supported	File type not in allowed list
2003	Insufficient storage space	User storage quota full
2004	Upload failed	Network or server error
2005	Chunk upload failed	Chunk verification failed
2006	File already exists	Same file already uploaded
2007	URL download failed	Network connection issue

🧪 Testing Examples

Basic File Upload

bash

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

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

Chunked Upload Example

bash

# 1. Initialize chunked upload
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. Upload chunk (example: upload chunk 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. Complete upload
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"
  }'

🔄 Changelog

v1.0.0 (2024-01-01)

Basic file upload APIs
Multiple files upload support
Chunked upload (resumable)
URL upload functionality
File management APIs
Image processing features
Upload statistics information

🔗 Related Links: API Overview

File Upload API ​

📤 Basic Upload APIs ​

Single File Upload ​

Multiple Files Upload ​

🔄 Chunked Upload APIs ​

Initialize Chunked Upload ​

Upload Chunk ​

Complete Chunked Upload ​

🌐 URL Upload APIs ​

URL Upload ​

📁 File Management APIs ​

Get File Information ​

Delete File ​

Batch Delete Files ​

🖼️ Image Processing APIs ​

Generate Thumbnail ​

Get Image Information ​

📊 Upload Statistics APIs ​

Get Upload Statistics ​

🔧 Configuration APIs ​

Get Upload Configuration ​

⚠️ Error Codes ​

🧪 Testing Examples ​

Basic File Upload ​

Chunked Upload Example ​

🔄 Changelog ​

v1.0.0 (2024-01-01) ​

File Upload API

📤 Basic Upload APIs

Single File Upload

Multiple Files Upload

🔄 Chunked Upload APIs

Initialize Chunked Upload

Upload Chunk

Complete Chunked Upload

🌐 URL Upload APIs

URL Upload

📁 File Management APIs

Get File Information

Delete File

Batch Delete Files

🖼️ Image Processing APIs

Generate Thumbnail

Get Image Information

📊 Upload Statistics APIs

Get Upload Statistics

🔧 Configuration APIs

Get Upload Configuration

⚠️ Error Codes

🧪 Testing Examples

Basic File Upload

Chunked Upload Example

🔄 Changelog

v1.0.0 (2024-01-01)