API 文档
CloudStorage API 完整文档，包含所有端点说明、参数详情和代码示例
快速开始
通过以下步骤快速了解如何使用 CloudStorage API
1
获取 API 基础地址
CloudStorage API 的基础地址
http://localhost:3000/api2
上传文件
使用 POST 请求上传文件
curl -X POST \
http://localhost:3000/api/files/upload \
-F "file=@example.txt"3
获取文件列表
使用 GET 请求获取所有文件
curl -X GET \
http://localhost:3000/api/files/upload4
下载文件
使用文件 ID 下载文件
curl -X GET \
http://localhost:3000/api/files/download/{fileId} \
-o downloaded-file.txt需要更多帮助？
查看完整的 API 文档和更多代码示例
API 端点
CloudStorage 提供的所有 API 端点详细说明
POST
/api/files/upload
上传文件到云存储
参数
fileFile
必需
要上传的文件
响应
200
文件上传成功{
"success": true,
"fileId": "abc123",
"filename": "example.txt",
"size": 1024,
"uploadedAt": "2024-01-01T00:00:00Z"
}400
上传失败{
"success": false,
"error": "No file provided"
}GET
/api/files/upload
获取所有已上传的文件列表
响应
200
成功获取文件列表{
"success": true,
"files": [
{
"id": "abc123",
"filename": "example.txt",
"size": 1024,
"uploadedAt": "2024-01-01T00:00:00Z"
}
]
}500
服务器错误{
"success": false,
"error": "Internal server error"
}GET
/api/files/download/{fileId}
下载指定的文件
参数
fileIdstring
必需
文件的唯一标识符
响应
200
文件下载成功Binary file content with proper headers404
文件未找到{
"success": false,
"error": "File not found"
}DELETE
/api/files/{fileId}
删除指定的文件
参数
fileIdstring
必需
要删除文件的唯一标识符
响应
200
文件删除成功{
"success": true,
"message": "File deleted successfully"
}404
文件未找到{
"success": false,
"error": "File not found"
}代码示例
多种编程语言的完整调用示例
cURL
命令行工具# 上传文件
curl -X POST \
http://localhost:3000/api/files/upload \
-F "file=@example.txt" \
-H "Content-Type: multipart/form-data"
# 响应示例
{
"success": true,
"fileId": "abc123",
"filename": "example.txt",
"size": 1024,
"uploadedAt": "2024-01-01T00:00:00Z"
}系统特性
安全可靠
支持多种存储后端，数据安全有保障
- 支持本地存储、Supabase、PocketBase
- 文件上传进度实时跟踪
- 完整的错误处理机制
- 文件元数据完整保存
高性能
优化的文件处理和传输机制
- 流式文件上传
- 并发请求支持
- 智能缓存策略
- 压缩传输优化
易于集成
RESTful API 设计，支持多种编程语言
- 标准 HTTP 协议
- JSON 格式响应
- 详细的错误码说明
- 完整的 API 文档
HTTP 状态码
API 响应状态码说明
了解不同状态码的含义，便于错误处理和调试
200
OK请求成功
400
Bad Request请求参数错误或缺失
404
Not Found请求的资源不存在
413
Payload Too Large上传文件过大
415
Unsupported Media Type不支持的文件类型
500
Internal Server Error服务器内部错误
最佳实践
请求超时处理
建议设置合理的请求超时时间，特别是对于大文件上传
// JavaScript 示例
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30秒超时
fetch('/api/files/upload', {
method: 'POST',
body: formData,
signal: controller.signal
}).finally(() => {
clearTimeout(timeoutId);
});错误重试机制
实现指数退避的重试策略，提高上传成功率
// Python 示例
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
session = requests.Session()
retry_strategy = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)文件大小限制
在客户端预先检查文件大小，避免无效请求
// JavaScript 示例
const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
function validateFile(file) {
if (file.size > MAX_FILE_SIZE) {
throw new Error('文件大小不能超过 10MB');
}
const allowedTypes = ['image/jpeg', 'image/png', 'text/plain'];
if (!allowedTypes.includes(file.type)) {
throw new Error('不支持的文件类型');
}
return true;
}安全考虑
实施适当的安全措施保护您的 API
// 安全建议
1. 使用 HTTPS 加密传输
2. 实施速率限制防止滥用
3. 验证文件类型和内容
4. 设置合理的文件大小限制
5. 记录和监控 API 使用情况
6. 定期清理过期文件