首页 > 脚本专栏 > python > Python FastAPI文件上传

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

2025-06-18 11:04:52 作者：源滚滚编程

在Web开发中,文件上传是刚需功能,FastAPI凭借异步架构和类型提示,让文件上传既简洁又强大,下面小编就来和大家详细讲讲如何使用FastAPI玩转文件上传功能吧

一核心武器：UploadFile和File()

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：支持大文件流式处理，自带异步接口

二上传实战四步曲

1. 基础保存：直接写入磁盘

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"}

2. 流式处理：应对大文件

@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)  #

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

3. 文件元信息：一键获取关键数据

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

4. 多文件上传：一次接收多个

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

三安全加固：限制与校验

1. 文件类型过滤

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格式")  #

2. 文件大小控制

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

3. 文件名消毒

import re

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

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

四高阶技巧：性能与体验优化

1. 临时文件处理

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  # 获取临时文件路径
    # ...后续处理

2. 客户端调用示例

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)  #

3. 文档增强技巧

给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文件上传内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！