如何使用 Python 和 FastAPI 处理文件上传
FastAPI 是一个现代、快速（高性能）的 Web 框架，用于基于标准 Python 类型提示构建 API。在 Web 开发中，文件上传是一个非常常见的需求，FastAPI 提供了简单而强大的工具来处理这一任务。本文将详细介绍如何使用 FastAPI 处理单文件上传、多文件上传、带有表单数据的文件上传，以及文件保存的最佳实践。
1. 环境准备
在开始之前，请确保已经安装了 FastAPI 和 Uvicorn。此外，处理文件上传需要依赖 python-multipart 库，请一并安装：
pip install fastapi uvicorn python-multipart
2. 基础单文件上传
FastAPI 提供了 UploadFile 和 File 两个核心组件来处理上传的文件。UploadFile 相比原生的 bytes 对象具有更多优势：它不会将所有数据一次性加载到内存中，而是使用临时文件存储，适合处理大文件；同时它提供了丰富的文件元数据（如文件名、内容类型等）。
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile = File(...)):
return {
"filename": file.filename,
"content_type": file.content_type
}在这个例子中，File(...) 表示该文件参数是必填的。如果客户端没有提供文件，FastAPI 将返回验证错误。
3. 多文件上传
如果需要同时上传多个文件，可以使用 Python 的列表类型 List[UploadFile] 来接收。
from typing import List
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile] = File(...)):
filenames = [file.filename for file in files]
return {"uploaded_filenames": filenames}4. 文件与表单数据混合上传
在实际业务场景中，我们经常需要在上传文件的同时传递一些额外的表单字段（如文件描述、分类等）。FastAPI 允许同时声明 File 和 Form 参数。
from fastapi import FastAPI, File, UploadFile, Form
app = FastAPI()
@app.post("/upload_with_form/")
async def upload_with_form(
file: UploadFile = File(...),
description: str = Form(...)
):
return {
"filename": file.filename,
"description": description
}请注意，当同时使用 File 和 Form 时，请求的 Content-Type 必须是 multipart/form-data。
5. 保存上传的文件
接收到文件后，通常需要将其保存到服务器的磁盘或对象存储中。为了不阻塞主线程，推荐使用异步方式写入文件。可以使用 aiofiles 库来实现异步文件 I/O 操作。
首先安装 aiofiles：
pip install aiofiles
然后编写保存逻辑：
import os
import aiofiles
from fastapi import FastAPI, UploadFile, File, HTTPException
app = FastAPI()
@app.post("/savefile/")
async def save_upload_file(file: UploadFile = File(...)):
upload_dir = "uploads"
os.makedirs(upload_dir, exist_ok=True)
# 安全处理文件名，防止路径遍历攻击
safe_filename = os.path.basename(file.filename)
if not safe_filename:
raise HTTPException(status_code=400, detail="Invalid filename")
file_path = os.path.join(upload_dir, safe_filename)
try:
async with aiofiles.open(file_path, 'wb') as out_file:
while content := await file.read(1024 * 1024): # 每次读取 1MB
await out_file.write(content)
except Exception as e:
raise HTTPException(status_code=500, detail=f"File save error: {str(e)}")
return {"message": "File saved successfully", "path": file_path}在上述代码中，我们使用了分块读取（每次读取 1MB）的方式，这样可以有效控制内存使用，即使是超大文件也不会导致内存溢出。
6. 最佳实践与安全考量
处理文件上传时，安全性至关重要。以下是一些关键的最佳实践：
限制文件大小： 可以通过 FastAPI 的中间件或 Nginx 等反向代理来限制请求体大小，防止恶意用户上传超大文件耗尽服务器资源。
验证文件类型： 不要仅依赖客户端提供的
content_type，因为它可以被伪造。建议通过读取文件头（Magic Number）或使用第三方库来验证文件的实际类型。安全文件名： 永远不要直接使用用户上传的文件名保存文件，务必使用
os.path.basename()剔除可能的路径信息，或者直接使用 UUID 生成新的文件名。隔离存储： 将上传的文件存储在非执行目录下，防止用户上传并执行恶意脚本（如 .php, .py, .exe 文件）。
7. 测试接口
你可以使用 FastAPI 自带的交互式文档（通常位于 http://www.ipipp.com/docs）来快速测试这些文件上传接口，也可以使用 curl 命令进行测试：
curl -X POST "http://www.ipipp.com/uploadfile/" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "file=@/path/to/your/local/file.txt"
总结
FastAPI 通过 UploadFile 和 File 提供了优雅且高效的文件上传处理机制。结合异步文件写入和严格的安全校验，开发者可以轻松构建出高性能、高安全性的文件处理服务。务必在生产环境中关注文件大小限制、类型校验和存储安全，以保障系统的稳定运行。