Python使用FastAPI實現(xiàn)文件上傳接口的最佳方案
引言
在現(xiàn)代 Web 應(yīng)用中，文件上傳幾乎是所有系統(tǒng)的標(biāo)配功能：無論是頭像上傳、文檔提交，還是批量導(dǎo)入數(shù)據(jù)。 本文將詳細(xì)介紹如何使用 FastAPI 快速、高效地實現(xiàn)文件上傳接口，并給出進(jìn)階場景（如多文件上傳、限制文件大小、異步保存文件等）的最佳實踐。
一、FastAPI 文件上傳的核心機(jī)制
FastAPI 內(nèi)置了強(qiáng)大的文件上傳支持，基于 starlette 的 UploadFile 對象實現(xiàn)。 它的底層使用 Python 的異步文件處理機(jī)制，性能優(yōu)于傳統(tǒng)的同步文件讀取。
在 FastAPI 中，文件上傳參數(shù)可以通過以下兩種類型聲明：
File(...)：用于聲明表單中的文件字段。UploadFile：封裝上傳文件對象，包含filename、content_type、file等屬性。
二、單文件上傳示例
先看一個最簡單的例子：上傳一個文件并保存到服務(wù)器。
from fastapi import FastAPI, File, UploadFile
import shutil
import os
app = FastAPI()
UPLOAD_DIR = "uploads"
os.makedirs(UPLOAD_DIR, exist_ok=True)
@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
file_path = os.path.join(UPLOAD_DIR, file.filename)
# 保存文件
with open(file_path, "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"filename": file.filename, "content_type": file.content_type}
說明：
UploadFile是一個異步文件對象（底層為SpooledTemporaryFile）。file.file是標(biāo)準(zhǔn)的類文件對象，可直接讀寫。shutil.copyfileobj()用于高效復(fù)制二進(jìn)制數(shù)據(jù)流。
訪問接口：
curl -F "file=@example.png" http://127.0.0.1:8000/upload/
返回：
{
"filename": "example.png",
"content_type": "image/png"
}
三、多文件上傳
FastAPI 支持一次性上傳多個文件，只需將類型改為 List[UploadFile]：
from typing import List
from fastapi import UploadFile, File
@app.post("/upload/multiple/")
async def upload_multiple(files: List[UploadFile] = File(...)):
saved_files = []
for file in files:
file_path = os.path.join(UPLOAD_DIR, file.filename)
with open(file_path, "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
saved_files.append(file.filename)
return {"uploaded_files": saved_files}
上傳多個文件：
curl -F "files=@a.png" -F "files=@b.jpg" http://127.0.0.1:8000/upload/multiple/
四、異步寫入與性能優(yōu)化
上面的寫入方式是同步的。如果文件較大，可能阻塞事件循環(huán)。 可以使用異步文件寫入方式提升性能（推薦在高并發(fā)或大文件場景）：
import aiofiles
@app.post("/upload/async/")
async def upload_file_async(file: UploadFile = File(...)):
file_path = os.path.join(UPLOAD_DIR, file.filename)
async with aiofiles.open(file_path, 'wb') as out_file:
while content := await file.read(1024):
await out_file.write(content)
await file.close()
return {"filename": file.filename}
提示：aiofiles 是一個異步文件操作庫，可與 FastAPI 無縫協(xié)作。
安裝依賴：
pip install aiofiles
五、限制上傳文件大小與類型
限制大小（Nginx / Uvicorn 層）
FastAPI 本身不限制文件大小。建議在 網(wǎng)關(guān)層（如 Nginx）限制上傳大小：
client_max_body_size 10M;
校驗文件類型
你可以在接口中檢查文件類型：
ALLOWED_TYPES = ["image/png", "image/jpeg"]
@app.post("/upload/image/")
async def upload_image(file: UploadFile = File(...)):
if file.content_type not in ALLOWED_TYPES:
return {"error": "Unsupported file type"}
# 繼續(xù)保存邏輯...
return {"filename": file.filename}
六、結(jié)合 Pydantic 校驗表單 + 文件混合上傳
在實際業(yè)務(wù)中，文件上傳通常伴隨表單數(shù)據(jù)（如用戶ID、描述等）。 FastAPI 支持文件與表單字段混合處理：
from fastapi import Form
@app.post("/upload/with_form/")
async def upload_with_form(
user_id: int = Form(...),
description: str = Form(""),
file: UploadFile = File(...)
):
file_path = os.path.join(UPLOAD_DIR, file.filename)
with open(file_path, "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"user_id": user_id, "description": description, "filename": file.filename}
七、實際應(yīng)用場景建議
| 場景 | 推薦方案 |
|---|---|
| 上傳頭像、小文件 | 使用 UploadFile + 異步保存 |
| 批量導(dǎo)入Excel、CSV | 使用 aiofiles 逐行讀取，解析后入庫 |
| 上傳到云存儲（如OSS、S3） | 直接使用 boto3 或 oss2 SDK，將文件流轉(zhuǎn)存至云端 |
| 接口網(wǎng)關(guān)安全限制 | 使用 Nginx / Traefik 限制文件大小和MIME類型 |
| 文件命名沖突 | 使用 UUID 或時間戳重命名文件 |
八、總結(jié)
FastAPI 讓文件上傳的實現(xiàn)變得異常簡單且高效。 通過本文的實踐，你已經(jīng)學(xué)會了：
- ? 基本文件上傳與保存
- ? 多文件與異步寫入
- ? 文件類型與大小校驗
- ? 表單與文件混合上傳
- ? 性能與安全最佳實踐
接下來，你可以嘗試：
- 實現(xiàn)一個圖片上傳 + 自動壓縮接口
- 結(jié)合 JWT 用戶認(rèn)證，構(gòu)建安全的文件上傳系統(tǒng)
- 將文件元數(shù)據(jù)存儲在數(shù)據(jù)庫中，實現(xiàn)可追蹤的文件管理系統(tǒng)
建議
在實際項目中，推薦將文件上傳邏輯封裝為獨(dú)立的服務(wù)模塊（如 services/file_service.py）， 結(jié)合日志（如 loguru）和異常處理中間件，讓系統(tǒng)更加可維護(hù)與可追蹤。
以上就是Python使用FastAPI實現(xiàn)文件上傳接口的最佳方案的詳細(xì)內(nèi)容，更多關(guān)于Python FastAPI文件上傳接口的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
python基礎(chǔ)學(xué)習(xí)之生成器與文件系統(tǒng)知識總結(jié)
本文是參考《python數(shù)據(jù)分析》的附錄對生成器和文件系統(tǒng)結(jié)合案例的一個簡單回顧,文中對python生成器與文件系統(tǒng)作了非常詳細(xì)的介紹,對正在學(xué)習(xí)python的小伙伴們有很好地幫助,需要的朋友可以參考下2021-05-05
Pycharm關(guān)于遠(yuǎn)程JupyterLab以及JupyterHub登錄問題
這篇文章主要介紹了Pycharm關(guān)于遠(yuǎn)程JupyterLab以及JupyterHub登錄問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-06-06
Django--權(quán)限Permissions的例子
今天小編就為大家分享一篇Django--權(quán)限Permissions的例子，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2019-08-08
Python的可視化有很多種，這篇文章主要介紹了Python可視化的顏色映射，非常不錯，具有一定的參考借鑒價值,需要的朋友可以參考下2021-09-09
python?sklearn數(shù)據(jù)預(yù)處理之?dāng)?shù)據(jù)縮放詳解
數(shù)據(jù)的預(yù)處理是數(shù)據(jù)分析,或者機(jī)器學(xué)習(xí)訓(xùn)練前的重要步驟,這篇文章主要為大家詳細(xì)介紹了sklearn數(shù)據(jù)預(yù)處理中數(shù)據(jù)縮放的相關(guān)知識,感興趣的小伙伴可以學(xué)習(xí)一下2023-10-10
今天小編就為大家分享一篇pytorch 自定義卷積核進(jìn)行卷積操作方式，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2019-12-12
這篇文章主要介紹了python學(xué)習(xí)之列表的運(yùn)用，文章首先通過創(chuàng)建列表展開列表運(yùn)用的相關(guān)資料，具有一定的參考價值，需要的小伙伴可以參考一下2022-05-05
Python 圖片文字識別的實現(xiàn)之PaddleOCR
OCR方向的工程師，之前一定聽說過PaddleOCR這個項目，其主要推薦的PP-OCR算法更是被國內(nèi)外企業(yè)開發(fā)者廣泛應(yīng)用，短短半年時間，累計Star數(shù)量已超過15k，頻頻登上Github Trending和Paperswithcode 日榜月榜第一2021-11-11
這篇文章主要介紹了python小球落地問題及解決(遞歸函數(shù))，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-05-05
這篇文章主要為大家詳細(xì)介紹了python實現(xiàn)密碼強(qiáng)度校驗，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價值，感興趣的小伙伴們可以參考一下2020-03-03