如何在 FastAPI 中高效实现文件上传：大文件与小文件完整指南

最近在开发一个需要处理大量文件上传的项目时，深刻体会到了文件上传功能的重要性。无论是用户上传头像这样的小文件，还是处理视频、文档这样的大文件，一个健壮的文件上传实现都是不可或缺的。今天就让我们一起深入探讨如何在 FastAPI 中优雅地处理文件上传。

文件上传的基本原理

在开始具体实现之前，我们先聊聊文件上传的基本原理。在 HTTP 协议中，文件上传通常通过 POST 请求，并使用 multipart/form-data 格式。这种格式允许我们在一个请求中发送多个不同类型的数据，包括文件和普通表单字段。

快速上手：处理小文件上传

对于小文件（比如用户头像），我们可以使用 FastAPI 的 UploadFile 类直接处理。这里有一个简单的示例：

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse
import uuid

app = FastAPI()

@app.post("/upload/small/")
async def upload_small_file(file: UploadFile = File(...)):
    try:
        # 读取文件内容
        content = await file.read()
        
        # 生成唯一文件名
        file_name = f"{uuid.uuid4()}_{file.filename}"
        
        # 验证文件类型
        if file.content_type not in ["image/jpeg", "image/png"]:
            return {"error": "只支持 JPEG 和 PNG 格式的图片"}
            
        # 验证文件大小（限制为 5MB）
        if len(content) > 5 * 1024 * 1024:
            return {"error": "文件大小超过 5MB 限制"}
            
        # 保存文件
        with open(f"uploads/{file_name}", "wb") as f:
            f.write(content)
            
        return {
            "filename": file_name,
            "content_type": file.content_type,
            "size": len(content)
        }
    except Exception as e:
        return {"error": f"上传失败: {str(e)}"}

@app.get("/")
async def upload_form():
    return HTMLResponse("""
        <form action="/upload/small/" enctype="multipart/form-data" method="post">
            <input name="file" type="file">
            <button type="submit">上传</button>
        </form>
    """)

进阶：异步处理大文件上传

当需要处理大文件时，我们不能简单地将整个文件读入内存。这时就需要使用分块读取和异步写入的方式：

import aiofiles
import os
from fastapi import FastAPI, File, UploadFile, HTTPException
from typing import Optional

app = FastAPI()

async def save_upload_file_chunks(upload_file: UploadFile, destination: str, chunk_size: int = 1024 * 1024):
    try:
        async with aiofiles.open(destination, 'wb') as out_file:
            while chunk := await upload_file.read(chunk_size):
                await out_file.write(chunk)
        return True
    except Exception as e:
        print(f"保存文件时发生错误: {str(e)}")
        return False

@app.post("/upload/large/")
async def upload_large_file(
    file: UploadFile = File(...),
    chunk_size: Optional[int] = 1024 * 1024  # 默认chunk大小为1MB
):
    try:
        # 创建上传目录（如果不存在）
        os.makedirs("large_uploads", exist_ok=True)
        
        # 生成唯一文件名
        file_name = f"{uuid.uuid4()}_{file.filename}"
        file_path = f"large_uploads/{file_name}"
        
        # 分块保存文件
        save_success = await save_upload_file_chunks(
            file, file_path, chunk_size
        )
        
        if not save_success:
            raise HTTPException(status_code=500, detail="文件保存失败")
            
        return {
            "filename": file_name,
            "content_type": file.content_type,
            "location": file_path
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

云存储集成：AWS S3 示例

在生产环境中，我们通常会使用云存储服务。这里以 AWS S3 为例：

import boto3
from botocore.exceptions import ClientError
from fastapi import FastAPI, File, UploadFile

app = FastAPI()

# 初始化 S3 客户端
s3_client = boto3.client(
    's3',
    aws_access_key_id='your_access_key',
    aws_secret_access_key='your_secret_key',
    region_name='your_region'
)

async def upload_to_s3(file: UploadFile, bucket: str, object_name: str):
    try:
        # 读取文件内容
        file_content = await file.read()
        
        # 上传到 S3
        s3_client.put_object(
            Bucket=bucket,
            Key=object_name,
            Body=file_content,
            ContentType=file.content_type
        )
        
        # 生成文件的公共URL
        url = f"https://{bucket}.s3.amazonaws.com/{object_name}"
        return url
    except ClientError as e:
        print(f"上传到 S3 时发生错误: {e}")
        return None

@app.post("/upload/s3/")
async def upload_file_to_s3(file: UploadFile = File(...)):
    try:
        bucket_name = "your-bucket-name"
        object_name = f"uploads/{uuid.uuid4()}_{file.filename}"
        
        # 上传文件到 S3
        file_url = await upload_to_s3(file, bucket_name, object_name)
        
        if not file_url:
            raise HTTPException(status_code=500, detail="上传到 S3 失败")
            
        return {
            "filename": file.filename,
            "url": file_url
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

处理跨域请求

在实际应用中，我们经常需要处理来自不同域的上传请求。以下是如何在 FastAPI 中配置 CORS：

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# 配置 CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # 允许的源
    allow_credentials=True,
    allow_methods=["*"],  # 允许的 HTTP 方法
    allow_headers=["*"],  # 允许的 HTTP 头
)

文件上传安全性增强

安全性是文件上传中最重要的考虑因素之一。这里有一个更完整的安全检查示例：

import magic
import hashlib
import asyncio
import aiofiles
from typing import List, Set

class FileValidator:
    def __init__(self):
        self.allowed_types: Set[str] = {
            'image/jpeg', 'image/png', 'application/pdf'
        }
        self.max_file_size: int = 10 * 1024 * 1024  # 10MB
        
    async def validate_file(self, file: UploadFile) -> tuple[bool, str]:
        # 检查文件类型
        if file.content_type not in self.allowed_types:
            return False, "不支持的文件类型"
            
        # 读取文件头部以验证真实文件类型
        header = await file.read(2048)
        await file.seek(0)  # 重置文件指针
        
        mime_type = magic.from_buffer(header, mime=True)
        if mime_type not in self.allowed_types:
            return False, "文件类型与扩展名不匹配"
            
        # 检查文件大小
        file_size = 0
        while chunk := await file.read(8192):
            file_size += len(chunk)
            if file_size > self.max_file_size:
                return False, "文件大小超过限制"
        await file.seek(0)
        
        # 计算文件哈希
        sha256_hash = hashlib.sha256()
        while chunk := await file.read(8192):
            sha256_hash.update(chunk)
        await file.seek(0)
        
        return True, sha256_hash.hexdigest()

@app.post("/upload/secure/")
async def secure_upload(file: UploadFile = File(...)):
    validator = FileValidator()
    is_valid, result = await validator.validate_file(file)
    
    if not is_valid:
        raise HTTPException(status_code=400, detail=result)
        
    # 文件通过验证，result 中包含文件哈希值
    file_hash = result
    
    # 这里继续处理文件上传...
    return {"message": "文件上传成功", "file_hash": file_hash}

最佳实践总结

1. 异步处理：利用 FastAPI 的异步特性，使用 aiofiles 进行文件操作。

2. 分块处理：对于大文件，始终使用分块读取和写入，避免内存溢出。

3. 安全性：

   • 验证文件类型和大小
   • 使用安全的文件命名策略
   • 实施病毒扫描
   • 设置适当的文件权限

4. 错误处理：

   • 捕获并处理所有可能的异常
   • 提供清晰的错误信息
   • 实现适当的日志记录

5. 存储策略：

   • 考虑使用云存储服务
   • 实现文件备份机制
   • 建立文件清理策略

6. 性能优化：

   • 使用异步IO
   • 实现断点续传
   • 考虑使用CDN

结语

文件上传看似简单，但要做好确实不易。需要考虑的因素包括性能、安全性、可靠性等多个方面。希望这篇文章能帮助你在 FastAPI 中实现一个健壮的文件上传功能。记住，在实际应用中，要根据具体需求选择合适的实现方案，并始终把安全性放在首位。

如果你觉得这篇文章有帮助，欢迎分享给其他开发者。如果你有任何问题或建议，也欢迎在评论区留言讨论。