Python如何使用FastAPI玩转文件上传功能

目录

• 一核心武器：UploadFile和File()
• 二上传实战四步曲
• 1. 基础保存：直接写入磁盘
• 2. 流式处理：应对大文件
• 3. 文件元信息：一键获取关键数据
• 4. 多文件上传：一次接收多个
• 三安全加固：限制与校验
• 1. 文件类型过滤
• 2. 文件大小控制
• 3. 文件名消毒
• 四高阶技巧：性能与体验优化
• 1. 临时文件处理
• 2. 客户端调用示例
• 3. 文档增强技巧
• 五避坑指南（血泪总结！）

FastAPI处理文件上传只需两个关键组件：

from fastapi import FastAPI, UploadFile, File

app = FastAPI()

​​​​​​​@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):  # 
    return {"filename": file.filename}

关键解析：

• UploadFile：智能文件对象，自动处理内存/磁盘存储切换，适合大文件
• File(…)：声明表单文件字段，…表示参数必填

优势对比：

• bytes = File()：适合小文件（默认上限1MB），直接读入内存
• UploadFile：支持大文件流式处理，自带异步接口

import shutil

​​​​​​​@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    with open(file.filename, "wb") as buffer:
        shutil.copyfileobj(file.file, buffer)  # 
    return {"status": "success"}

@app.post("/large-upload/")
async def large_upload(file: UploadFile):
    with open(file.filename, "wb") as f:
        while chunk := await file.read(1024 * 1024):  # 每次读取1MB
            f.write(chunk)  # 

为何更优：避免单次读取导致内存溢出

@app.post("/meta-upload/")
async def meta_upload(file: UploadFile):
    return {
        "文件名": file.filename,
        "类型": file.content_type,  # 如image/png
        "大小": f"{file.size / 1024:.2f} KB"  # 
    }

@app.post("/multi-upload/")
async def multi_upload(files: list[UploadFile] = File(...)):  # 👈 注意list
    return {"count": len(files), "names": [f.filename for f in files]}

ALLOWED_TYPES = ["image/jpeg", "image/png"]

@app.post("/safe-upload/")
async def safe_upload(file: UploadFile):
    if file.content_type not in ALLOWED_TYPES:
        raise HTTPException(400, "仅支持JPG/PNG格式")  # 

@app.post("/size-limit/")
async def size_limit(
    file: UploadFile = File(..., max_size=100_000_000)  # 限制100MB
):
    ...  # 

import re

def sanitize_filename(filename: str) -> str:
    return re.sub(r"[^w.]", "", filename)  # 移除非法字符

# 使用：sanitized_name = sanitize_filename(file.filename)

import tempfile


@app.post("/temp-upload/")
async def temp_upload(file: UploadFile):
    with tempfile.NamedTemporaryFile(delete=False, suffix=".tmp") as tmp:
        shutil.copyfileobj(file.file, tmp)
        tmp_path = tmp.name  # 获取临时文件路径
    # ...后续处理

CURL命令：

curl -X POST "http://localhost:8000/upload/" 
  -H "Content-Type: multipart/form-data" 
  -F "file=@cat.jpg"  # 

Python Requests调用：

import requests
url = "http://localhost:8000/upload/"
files = {"file": open("cat.jpg", "rb")}
response = requests.post(url, files=files)  # 

给Swagger文档添加文件说明：

@app.post("/upload/", 
    summary="上传文件",
    description="支持图片/文档，最大100MB",
    response_description="返回文件名和大小"
)
async def upload_file(...): ...

1.遗忘python-multipart

必须安装：pip install python-multipart，否则报错Form data parsing error

2.同步阻塞写入

• 避免：content = file.file.read()（大文件卡死进程）
• 正确：await file.read() 异步读取

3.文件覆盖风险

多人上传同名文件时，采用唯一命名：

import uuid
filename = f"{uuid.uuid4()}_{file.filename}"

4.跨平台路径陷阱

使用pathlib处理路径：

from pathlib import Path
save_path = Path("uploads") / sanitize_filename(file.filename)

到此这篇关于Python如何使用FastAPI玩转文件上传功能的文章就介绍到这了,更多相关Python FastAPI文件上传内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• Python利用fastapi实现上传文件
• Python Fastapi实现统一处理各种异常
• Python FastAPI入门安装使用
• Python 搭建 FastAPI 项目的详细过程
• 使用Python FastAPI构建Web服务的实现