Awesome FastAPI文件处理：上传下载与流媒体服务实现
项目地址: https://gitcode.com/gh_mirrors/aw/awesome-fastapi 你是否还在为Web应用中的文件处理功能头疼？用户上传文件总是失败、大文件下载导致服务器崩溃、视频播放卡顿缓冲？本文将带你一文掌握FastAPI中文件上传、下载和流媒体服务的实现方案，让你轻松应对各种文件处理场景。读完本文你将学会：如何安全接收用户上传的文件、如何高效提供大文件下载服务、如何实现流畅的视频和音频流媒体播放，以及这些功能的最佳实践和性能优化技巧。
FastAPI文件处理基础
FastAPI作为一款现代高性能的Python Web框架，提供了简洁而强大的文件处理能力。它基于Starlette构建，原生支持异步I/O操作，非常适合处理文件上传下载这类I/O密集型任务。项目的README.md中详细介绍了FastAPI的核心特性，包括其高性能、易用性和对异步编程的支持，这些特性使得FastAPI成为构建文件处理服务的理想选择。
FastAPI的文件处理主要依赖于File和UploadFile两个核心组件。File用于处理小型文件，而UploadFile则适用于大型文件和流式上传，支持异步操作和文件元数据访问。这两个组件都与Pydantic深度集成，提供了自动的数据验证和类型提示功能。
文件上传功能实现
文件上传是Web应用中最常见的功能之一，无论是用户头像上传、文档提交还是媒体文件分享，都需要可靠的文件上传机制。FastAPI提供了简单而强大的API来处理文件上传，同时支持单文件和多文件上传。
单文件上传
以下是一个基本的单文件上传实现示例：
from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
import os
app = FastAPI()
# 确保上传目录存在
os.makedirs("uploads", exist_ok=True)
@app.post("/upload/single")
async def upload_single_file(file: UploadFile = File(...)):
try:
# 保存文件
file_path = f"uploads/{file.filename}"
with open(file_path, "wb") as f:
content = await file.read()
f.write(content)
return JSONResponse({
"success": True,
"filename": file.filename,
"content_type": file.content_type,
"size": len(content),
"message": "文件上传成功"
})
except Exception as e:
return JSONResponse(
{"success": False, "message": f"文件上传失败: {str(e)}"},
status_code=500
)
这个简单的实现已经包含了文件保存、错误处理和基本的元数据返回功能。UploadFile对象提供了文件名、内容类型等元数据，通过await file.read()可以异步读取文件内容。
多文件上传
FastAPI同样支持一次上传多个文件，只需将参数类型改为List[UploadFile]：
from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
from typing import List
import os
app = FastAPI()
os.makedirs("uploads", exist_ok=True)
@app.post("/upload/multiple")
async def upload_multiple_files(files: List[UploadFile] = File(...)):
results = []
for file in files:
try:
file_path = f"uploads/{file.filename}"
with open(file_path, "wb") as f:
content = await file.read()
f.write(content)
results.append({
"filename": file.filename,
"success": True,
"size": len(content)
})
except Exception as e:
results.append({
"filename": file.filename,
"success": False,
"message": str(e)
})
return JSONResponse({"results": results})
文件上传高级配置
对于生产环境，我们还需要添加文件大小限制、文件类型验证和安全的文件名处理等功能：
from fastapi import FastAPI, File, UploadFile, HTTPException
from fastapi.responses import JSONResponse
import os
import uuid
from typing import List
app = FastAPI()
# 配置
MAX_FILE_SIZE = 10 * 1024 * 1024 # 10MB
ALLOWED_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "pdf", "txt"}
UPLOAD_DIR = "uploads"
os.makedirs(UPLOAD_DIR, exist_ok=True)
def validate_file(file: UploadFile):
# 检查文件大小
if file.size > MAX_FILE_SIZE:
raise HTTPException(status_code=413, detail=f"文件大小超过限制: {MAX_FILE_SIZE//(1024*1024)}MB")
# 检查文件扩展名
ext = file.filename.split(".")[-1].lower()
if ext not in ALLOWED_EXTENSIONS:
raise HTTPException(status_code=400, detail=f"不支持的文件类型: {ext}。允许的类型: {', '.join(ALLOWED_EXTENSIONS)}")
def secure_filename(filename: str) -> str:
# 生成安全的文件名，避免路径遍历攻击
ext = filename.split(".")[-1].lower() if "." in filename else ""
return f"{uuid.uuid4()}.{ext}" if ext else str(uuid.uuid4())
@app.post("/upload/secure")
async def upload_secure_file(file: UploadFile = File(...)):
validate_file(file)
safe_name = secure_filename(file.filename)
file_path = os.path.join(UPLOAD_DIR, safe_name)
try:
with open(file_path, "wb") as f:
# 分块读取写入，避免占用过多内存
while content := await file.read(1024*1024): # 1MB chunks
f.write(content)
return JSONResponse({
"success": True,
"original_filename": file.filename,
"stored_filename": safe_name,
"content_type": file.content_type,
"size": file.size
})
except Exception as e:
raise HTTPException(status_code=500, detail=f"文件保存失败: {str(e)}")
文件下载功能实现
文件下载功能与上传同样重要。FastAPI提供了多种响应类型来实现文件下载，包括FileResponse和StreamingResponse，分别适用于不同场景。
基本文件下载
使用FileResponse可以轻松实现简单的文件下载：
from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
import os
app = FastAPI()
UPLOAD_DIR = "uploads"
@app.get("/download/{filename}")
async def download_file(filename: str):
file_path = os.path.join(UPLOAD_DIR, filename)
# 检查文件是否存在
if not os.path.exists(file_path):
raise HTTPException(status_code=404, detail="文件不存在")
# 返回文件响应
return FileResponse(
path=file_path,
filename=filename,
media_type="application/octet-stream"
)
FileResponse会自动处理文件的读取和响应头设置，包括Content-Length和Content-Disposition等。
大型文件流式下载
对于大型文件，使用StreamingResponse可以实现流式下载，避免一次性将整个文件读入内存：
from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
import os
from starlette.background import BackgroundTask
app = FastAPI()
UPLOAD_DIR = "uploads"
def file_iterator(file_path: str, chunk_size: int = 1024*1024):
"""生成文件内容的迭代器，用于流式传输"""
with open(file_path, "rb") as f:
while chunk := f.read(chunk_size):
yield chunk
@app.get("/stream/{filename}")
async def stream_file(filename: str):
file_path = os.path.join(UPLOAD_DIR, filename)
if not os.path.exists(file_path):
raise HTTPException(status_code=404, detail="文件不存在")
# 获取文件大小和类型
file_size = os.path.getsize(file_path)
media_type = "application/octet-stream"
# 返回流式响应
return StreamingResponse(
file_iterator(file_path),
media_type=media_type,
headers={
"Content-Length": str(file_size),
"Content-Disposition": f"attachment; filename={filename}"
}
)
带断点续传的下载服务
断点续传允许用户在下载中断后从中断处继续下载，而不必重新下载整个文件。这对于大型文件尤其重要：
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse
import os
app = FastAPI()
UPLOAD_DIR = "uploads"
def range_requests_response(file_path: str, request: Request):
"""处理带Range头的断点续传请求"""
file_size = os.path.getsize(file_path)
range_header = request.headers.get("Range")
if not range_header:
# 没有Range头，返回整个文件
return StreamingResponse(
file_iterator(file_path),
media_type="application/octet-stream",
headers={"Content-Length": str(file_size)}
)
# 解析Range头，格式如 "bytes=0-100"
range_start, range_end = 0, file_size - 1
units, range_str = range_header.split("=")
if units != "bytes":
raise HTTPException(status_code=416, detail="不支持的Range单位")
if "-" in range_str:
start_str, end_str = range_str.split("-", 1)
if start_str:
range_start = int(start_str)
if end_str:
range_end = int(end_str)
# 确保范围有效
if range_start >= file_size:
raise HTTPException(status_code=416, detail="请求的范围超出文件大小")
range_end = min(range_end, file_size - 1)
content_length = range_end - range_start + 1
# 生成部分文件内容
def partial_file_iterator():
with open(file_path, "rb") as f:
f.seek(range_start)
remaining = content_length
while remaining > 0:
chunk_size = min(remaining, 1024*1024)
chunk = f.read(chunk_size)
if not chunk:
break
remaining -= len(chunk)
yield chunk
# 返回部分内容响应
return StreamingResponse(
partial_file_iterator(),
status_code=206, # Partial Content
media_type="application/octet-stream",
headers={
"Content-Range": f"bytes {range_start}-{range_end}/{file_size}",
"Accept-Ranges": "bytes",
"Content-Length": str(content_length)
}
)
@app.get("/download/resumable/{filename}")
async def resumable_download(filename: str, request: Request):
file_path = os.path.join(UPLOAD_DIR, filename)
if not os.path.exists(file_path):
raise HTTPException(status_code=404, detail="文件不存在")
return range_requests_response(file_path, request)
流媒体服务实现
流媒体服务允许用户在文件完全下载完成前开始播放媒体文件，这极大地提升了用户体验，尤其是对于视频和音频文件。FastAPI的异步特性使其非常适合构建高效的流媒体服务。
视频流媒体服务
以下是一个支持HTML5视频播放器的流媒体服务实现：
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse
from fastapi.templating import Jinja2Templates
import os
app = FastAPI()
templates = Jinja2Templates(directory="templates")
MEDIA_DIR = "media/videos"
os.makedirs(MEDIA_DIR, exist_ok=True)
def video_streamer(file_path: str, start: int = 0, end: int = None):
"""视频流生成器"""
file_size = os.path.getsize(file_path)
end = end or file_size - 1
with open(file_path, "rb") as f:
f.seek(start)
while pos := f.tell() <= end:
chunk_size = min(1024*1024, end - pos + 1) # 1MB chunks
yield f.read(chunk_size)
@app.get("/video/{filename}")
async def stream_video(filename: str, request: Request):
file_path = os.path.join(MEDIA_DIR, filename)
if not os.path.exists(file_path):
raise HTTPException(status_code=404, detail="视频文件不存在")
file_size = os.path.getsize(file_path)
range_header = request.headers.get("Range", "")
if range_header:
# 解析Range头
range_start = 0
range_end = file_size - 1
if range_header.startswith("bytes="):
range_part = range_header[6:]
if "-" in range_part:
start_str, end_str = range_part.split("-", 1)
if start_str:
range_start = int(start_str)
if end_str:
range_end = int(end_str)
# 确保范围有效
if range_start >= file_size:
raise HTTPException(status_code=416, detail="请求的范围超出文件大小")
range_end = min(range_end, file_size - 1)
content_length = range_end - range_start + 1
return StreamingResponse(
video_streamer(file_path, range_start, range_end),
status_code=206,
media_type="video/mp4",
headers={
"Content-Range": f"bytes {range_start}-{range_end}/{file_size}",
"Accept-Ranges": "bytes",
"Content-Length": str(content_length)
}
)
else:
# 返回整个视频文件（不推荐用于大文件）
return StreamingResponse(
video_streamer(file_path),
media_type="video/mp4",
headers={"Content-Length": str(file_size)}
)
@app.get("/video-player/{filename}")
async def video_player(request: Request, filename: str):
"""提供一个简单的HTML5视频播放器页面"""
return templates.TemplateResponse("video_player.html", {
"request": request,
"filename": filename
})
对应的HTML模板文件（templates/video_player.html）：
<!DOCTYPE html>
<html>
<head>
<title>视频播放器</title>
<style>
.container { max-width: 800px; margin: 0 auto; padding: 20px; }
video { width: 100%; }
</style>
</head>
<body>
<div class="container">
<h1>HTML5 视频播放器</h1>
<video controls>
<source src="/video/{{ filename }}" type="video/mp4">
您的浏览器不支持HTML5视频播放。
</video>
</div>
</body>
</html>
音频流媒体服务
音频流媒体的实现与视频类似，但使用不同的媒体类型：
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse
import os
app = FastAPI()
MEDIA_DIR = "media/audio"
os.makedirs(MEDIA_DIR, exist_ok=True)
def audio_streamer(file_path: str, start: int = 0, end: int = None):
"""音频流生成器"""
file_size = os.path.getsize(file_path)
end = end or file_size - 1
with open(file_path, "rb") as f:
f.seek(start)
while pos := f.tell() <= end:
chunk_size = min(1024*128, end - pos + 1) # 128KB chunks for audio
yield f.read(chunk_size)
@app.get("/audio/{filename}")
async def stream_audio(filename: str, request: Request):
file_path = os.path.join(MEDIA_DIR, filename)
if not os.path.exists(file_path):
raise HTTPException(status_code=404, detail="音频文件不存在")
file_size = os.path.getsize(file_path)
range_header = request.headers.get("Range", "")
media_type = "audio/mpeg" if filename.endswith(".mp3") else "audio/wav"
# 处理Range请求头，实现断点续传
# 实现逻辑与视频流媒体类似，此处省略...
return StreamingResponse(
audio_streamer(file_path),
media_type=media_type,
headers={"Content-Length": str(file_size)}
)
实时数据流媒体
除了文件流媒体，FastAPI还可以用于实时数据流式传输，如传感器数据、日志流或实时分析结果。这可以通过WebSocket或服务器发送事件（SSE）实现。
以下是一个使用SSE的实时数据流式传输示例：
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
import asyncio
import time
import json
from datetime import datetime
app = FastAPI()
async def data_generator():
"""生成实时数据流"""
for i in range(100):
# 模拟实时数据，如传感器读数
data = {
"timestamp": datetime.now().isoformat(),
"value": i * 0.5,
"sensor_id": "sensor_001"
}
yield f"data: {json.dumps(data)}\n\n"
await asyncio.sleep(1) # 每秒发送一次数据
@app.get("/stream/data")
async def stream_data(request: Request):
"""实时数据流式传输端点"""
return StreamingResponse(
data_generator(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"Connection": "keep-alive"
}
)
客户端可以使用JavaScript的EventSourceAPI来接收这个数据流：
const eventSource = new EventSource("/stream/data");
eventSource.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log("Received data:", data);
// 更新UI显示
document.getElementById("data-value").textContent = data.value;
document.getElementById("data-timestamp").textContent = data.timestamp;
};
eventSource.onerror = function(error) {
console.error("EventSource error:", error);
eventSource.close();
};
文件处理最佳实践与性能优化
存储策略
对于生产环境的文件存储，有以下几种常见策略：
- 本地文件系统：简单直接，但不适合分布式部署和水平扩展。
- 对象存储服务：如AWS S3、Google Cloud Storage或阿里云OSS，适合大规模文件存储。
- 分布式文件系统：如Ceph或GlusterFS，适合需要高性能访问的场景。
以下是一个集成AWS S3的文件上传示例：
from fastapi import FastAPI, File, UploadFile, HTTPException
from fastapi.responses import JSONResponse
import boto3
from botocore.exceptions import NoCredentialsError
import os
import uuid
app = FastAPI()
# 配置AWS S3
AWS_ACCESS_KEY = os.getenv("AWS_ACCESS_KEY")
AWS_SECRET_KEY = os.getenv("AWS_SECRET_KEY")
AWS_BUCKET_NAME = os.getenv("AWS_BUCKET_NAME")
s3 = boto3.client(
"s3",
aws_access_key_id=AWS_ACCESS_KEY,
aws_secret_access_key=AWS_SECRET_KEY
)
@app.post("/upload/s3")
async def upload_to_s3(file: UploadFile = File(...)):
try:
# 生成安全的文件名
filename = f"{uuid.uuid4()}_{file.filename}"
# 直接流式上传到S3
s3.upload_fileobj(
file.file,
AWS_BUCKET_NAME,
filename,
ExtraArgs={"ContentType": file.content_type}
)
# 生成文件URL
file_url = f"https://{AWS_BUCKET_NAME}.s3.amazonaws.com/{filename}"
return JSONResponse({
"success": True,
"filename": filename,
"url": file_url,
"content_type": file.content_type
})
except NoCredentialsError:
raise HTTPException(status_code=500, detail="AWS凭据未配置")
except Exception as e:
raise HTTPException(status_code=500, detail=f"上传到S3失败: {str(e)}")
性能优化技巧
- 异步处理：充分利用FastAPI的异步特性，使用
async/await处理文件I/O。 - 分块传输：对于大文件，使用分块读取和写入，避免占用过多内存。
- 缓存策略：对频繁访问的文件实施缓存，可使用Redis或CDN。
- 压缩传输：对文本文件启用gzip压缩。
- 连接池：对于云存储服务，使用连接池减少连接建立开销。
- 后台任务：对于耗时的文件处理操作（如视频转码），使用后台任务处理。
以下是一个使用FastAPI后台任务处理文件的示例：
from fastapi import FastAPI, BackgroundTasks, UploadFile, File
from fastapi.responses import JSONResponse
import os
import uuid
import shutil
from moviepy.editor import VideoFileClip # 用于视频处理
app = FastAPI()
UPLOAD_DIR = "uploads"
PROCESSED_DIR = "processed"
os.makedirs(UPLOAD_DIR, exist_ok=True)
os.makedirs(PROCESSED_DIR, exist_ok=True)
def process_video(input_path: str, output_path: str):
"""视频处理后台任务：转换为多种分辨率"""
try:
with VideoFileClip(input_path) as video:
# 生成720p版本
video.resize(height=720).write_videofile(f"{output_path}_720p.mp4")
# 生成480p版本
video.resize(height=480).write_videofile(f"{output_path}_480p.mp4")
# 生成360p版本
video.resize(height=360).write_videofile(f"{output_path}_360p.mp4")
# 处理完成后删除原始文件
os.remove(input_path)
except Exception as e:
print(f"视频处理失败: {str(e)}")
@app.post("/upload/video")
async def upload_video(
background_tasks: BackgroundTasks,
file: UploadFile = File(...)
):
# 保存上传的视频文件
filename = str(uuid.uuid4())
input_path = os.path.join(UPLOAD_DIR, f"{filename}.mp4")
with open(input_path, "wb") as f:
shutil.copyfileobj(file.file, f)
# 添加后台任务处理视频
background_tasks.add_task(process_video, input_path, os.path.join(PROCESSED_DIR, filename))
return JSONResponse({
"success": True,
"message": "视频上传成功，正在后台处理",
"task_id": filename
})
安全考虑
文件处理功能需要特别注意安全问题：
- 文件名安全：始终验证和清理用户提供的文件名，避免路径遍历攻击。
- 文件类型验证：不要仅依赖文件扩展名，最好验证文件的魔术数字（magic number）。
- 文件大小限制：防止超大文件上传导致的存储耗尽或DoS攻击。
- 内容验证：对于可执行文件或脚本，考虑使用杀毒软件扫描。
- 访问控制：确保只有授权用户可以访问受保护的文件。
以下是一个文件类型验证的实现，通过检查文件的魔术数字来确定真实文件类型：
import imghdr
def validate_image_file(file_path: str):
"""验证文件是否为真实的图像文件"""
allowed_types = ["jpeg", "png", "gif", "bmp"]
file_type = imghdr.what(file_path)
return file_type in allowed_types
总结与展望
FastAPI提供了强大而灵活的文件处理能力，从简单的文件上传下载到复杂的流媒体服务，都可以通过简洁的API实现。其异步特性使其特别适合处理I/O密集型的文件操作，能够提供高性能的服务。
随着Web应用对媒体处理需求的增长，FastAPI在文件处理方面的应用将越来越广泛。未来，我们可以期待更多专门针对FastAPI的文件处理扩展库出现，进一步简化复杂媒体处理功能的实现。
无论你是构建简单的文件分享应用，还是复杂的媒体服务平台，FastAPI都能为你提供坚实的基础。通过本文介绍的技术和最佳实践，你可以构建出高效、可靠且安全的文件处理服务。
要了解更多FastAPI相关资源和最佳实践，可以参考项目的README.md文件，其中收录了大量有用的第三方扩展、教程和示例项目，帮助你更好地掌握FastAPI的各种高级特性和应用场景。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
