Zvládnutí nahrávání souborů ve FastAPI: Hloubkový ponor do zpracování formulářů Multipart

V moderních webových aplikacích je schopnost zpracovávat nahrávání souborů zásadním požadavkem. Ať už se jedná o uživatele odesílající profilové obrázky, dokumenty ke zpracování nebo média ke sdílení, robustní a efektivní mechanismy nahrávání souborů jsou klíčové. FastAPI, vysoce výkonný webový framework v Pythonu, v této oblasti vyniká a nabízí zjednodušené způsoby správy dat formulářů multipart, což je standard pro odesílání souborů přes HTTP. Tato komplexní příručka vás provede složitostmi nahrávání souborů ve FastAPI, od základní implementace po pokročilé aspekty, a zajistí, že budete moci s jistotou vytvářet výkonná a škálovatelná API pro globální publikum.

Porozumění datům formuláře Multipart

Než se ponoříme do implementace ve FastAPI, je nezbytné pochopit, co jsou data formuláře multipart. Když webový prohlížeč odešle formulář obsahující soubory, obvykle používá atribut enctype="multipart/form-data". Tento typ kódování rozděluje odeslání formuláře do několika částí, z nichž každá má svůj vlastní typ obsahu a informace o uspořádání. To umožňuje přenos různých typů dat v rámci jednoho požadavku HTTP, včetně textových polí, netextových polí a binárních souborů.

Každá část požadavku multipart se skládá z:

• Hlavička Content-Disposition: Určuje název pole formuláře (name) a pro soubory původní název souboru (filename).
• Hlavička Content-Type: Udává typ MIME části (např. text/plain, image/jpeg).
• Tělo: Skutečná data pro danou část.

Přístup FastAPI k nahrávání souborů

FastAPI využívá standardní knihovnu Pythonu a bezproblémově se integruje s Pydantic pro ověřování dat. Pro nahrávání souborů používá typ UploadFile z modulu fastapi. Tato třída poskytuje pohodlné a bezpečné rozhraní pro přístup k nahraným datům souboru.

Základní implementace nahrávání souborů

Začněme jednoduchým příkladem, jak vytvořit koncový bod ve FastAPI, který přijímá nahrávání jednoho souboru. Použijeme funkci File z fastapi k deklarování parametru souboru.

            from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/files/")
async def create_file(file: UploadFile):
    return {"filename": file.filename, "content_type": file.content_type}

            

              
                Copy
              
            
          

V tomto příkladu:

• Importujeme FastAPI, File a UploadFile.
• Koncový bod /files/ je definován jako požadavek POST.
• Parametr file je anotován pomocí UploadFile, což znamená, že očekává nahrání souboru.
• Uvnitř funkce koncového bodu můžeme přistupovat k vlastnostem nahraného souboru, jako je filename a content_type.

Když klient odešle požadavek POST na /files/ s připojeným souborem (obvykle prostřednictvím formuláře s enctype="multipart/form-data"), FastAPI automaticky zpracuje parsování a poskytne objekt UploadFile. Poté můžete s tímto objektem interagovat.

Ukládání nahraných souborů

Často budete muset uložit nahraný soubor na disk nebo zpracovat jeho obsah. Objekt UploadFile k tomu poskytuje metody:

• read(): Načte celý obsah souboru do paměti jako bajty. Použijte to pro menší soubory.
• write(content: bytes): Zapíše bajty do souboru.
• seek(offset: int): Změní aktuální pozici souboru.
• close(): Zavře soubor.

Je důležité zpracovávat operace se soubory asynchronně, zejména při práci s velkými soubory nebo úkoly vázanými na I/O. UploadFile FastAPI podporuje asynchronní operace.

            from fastapi import FastAPI, File, UploadFile
import shutil

app = FastAPI()

@app.post("/files/save/")
async def save_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
    return {"info": f"file '{file.filename}' saved at '{file_location}'"}

            

              
                Copy
              
            
          

V tomto vylepšeném příkladu:

• Používáme File(...) k označení, že tento parametr je povinný.
• Určíme místní cestu, kam bude soubor uložen. Ujistěte se, že adresář uploads existuje.
• Otevřeme cílový soubor v binárním režimu zápisu (`"wb+"`).
• Asynchronně načteme obsah nahraného souboru pomocí await file.read() a poté jej zapíšeme do místního souboru.

Poznámka: Načtení celého souboru do paměti pomocí await file.read() může být problematické u velmi velkých souborů. U takových scénářů zvažte streamování obsahu souboru.

Streamování obsahu souboru

U velkých souborů může načtení celého obsahu do paměti vést k nadměrné spotřebě paměti a potenciálním chybám nedostatku paměti. Efektivnější přístup z hlediska paměti je streamovat soubor po částech. Funkce shutil.copyfileobj je pro to vynikající, ale musíme ji přizpůsobit pro asynchronní operace.

            from fastapi import FastAPI, File, UploadFile
import aiofiles # Install using: pip install aiofiles

app = FastAPI()

@app.post("/files/stream/")
async def stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        content = await file.read()
        await out_file.write(content)
    return {"info": f"file '{file.filename}' streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

S aiofiles můžeme efektivně streamovat obsah nahraného souboru do cílového souboru, aniž bychom načetli celý soubor do paměti najednou. await file.read() v tomto kontextu stále čte celý soubor, ale aiofiles zpracovává zápis efektivněji. Pro skutečné streamování po částech s UploadFile byste obvykle iterovali přes await file.read(chunk_size), ale aiofiles.open a await out_file.write(content) je běžný a výkonný vzor pro ukládání.

Explicitnější přístup ke streamování pomocí chunkingu:

            from fastapi import FastAPI, File, UploadFile
import aiofiles

app = FastAPI()

CHUNK_SIZE = 1024 * 1024 # 1MB chunk size

@app.post("/files/chunked_stream/")
async def chunked_stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        while content := await file.read(CHUNK_SIZE):
            await out_file.write(content)
    return {"info": f"file '{file.filename}' chunked streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

Tento koncový bod `chunked_stream_file` čte soubor v blocích po 1 MB a zapisuje každý blok do výstupního souboru. Toto je nejekonomičtější způsob, jak zpracovat potenciálně velmi velké soubory.

Zpracování více nahrávání souborů

Webové aplikace často vyžadují, aby uživatelé nahrávali více souborů současně. FastAPI to usnadňuje.

Nahrávání seznamu souborů

Můžete přijmout seznam souborů anotováním parametru seznamem UploadFile.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/multiple/")
async def create_multiple_files(
    files: List[UploadFile] = File(...)
):
    results = []
    for file in files:
        # Process each file, e.g., save it
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {"files_processed": results}

            

              
                Copy
              
            
          

V tomto scénáři musí klient odeslat více částí se stejným názvem pole formuláře (např. `files`). FastAPI je shromáždí do seznamu Pythonu objektů UploadFile.

Kombinování souborů a dalších dat formuláře

Je běžné mít formuláře, které obsahují jak pole souborů, tak běžná textová pole. FastAPI to zvládá tím, že vám umožňuje deklarovat další parametry pomocí standardních typových anotací spolu s Form pro pole formuláře, která nejsou soubory.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/mixed/")
async def upload_mixed_data(
    description: str = Form(...),
    files: List[UploadFile] = File(...) # Accepts multiple files with the name 'files'
):
    results = []
    for file in files:
        # Process each file
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {
        "description": description,
        "files_processed": results
    }

            

              
                Copy
              
            
          

Při použití nástrojů, jako je Swagger UI nebo Postman, určíte description jako běžné pole formuláře a poté přidáte více částí pro pole files, každá s typem obsahu nastaveným na příslušný typ obrázku/dokumentu.

Pokročilé funkce a osvědčené postupy

Kromě základního zpracování souborů je pro vytváření robustních API pro nahrávání souborů zásadních několik pokročilých funkcí a osvědčených postupů.

Limity velikosti souborů

Povolení neomezeného nahrávání souborů může vést k útokům typu denial-of-service nebo nadměrné spotřebě zdrojů. Zatímco FastAPI samo o sobě ve výchozím nastavení nevynucuje pevné limity na úrovni frameworku, měli byste implementovat kontroly:

• Na úrovni aplikace: Zkontrolujte velikost souboru po jeho přijetí, ale před zpracováním nebo uložením.
• Na úrovni webového serveru/proxy: Nakonfigurujte svůj webový server (např. Nginx, Uvicorn s pracovníky) tak, aby odmítal požadavky překračující určitou velikost datové části.

Příklad kontroly velikosti na úrovni aplikace:

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

MAX_FILE_SIZE_MB = 10
MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024

@app.post("/files/limited_size/")
async def upload_with_size_limit(file: UploadFile = File(...)):
    if len(await file.read()) > MAX_FILE_SIZE_BYTES:
        raise HTTPException(status_code=400, detail=f"File is too large. Maximum size is {MAX_FILE_SIZE_MB}MB.")
    
    # Reset file pointer to read content again
    await file.seek(0)
    
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully."}

            

              
                Copy
              
            
          

Důležité: Po načtení souboru za účelem kontroly jeho velikosti musíte použít await file.seek(0) k resetování ukazatele souboru na začátek, pokud máte v úmyslu znovu načíst jeho obsah (např. k jeho uložení).

Povolené typy souborů (typy MIME)

Omezení nahrávání na konkrétní typy souborů zvyšuje zabezpečení a zajišťuje integritu dat. Můžete zkontrolovat atribut content_type objektu UploadFile.

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

ALLOWED_FILE_TYPES = {"image/jpeg", "image/png", "application/pdf"}

@app.post("/files/restricted_types/")
async def upload_restricted_types(file: UploadFile = File(...)):
    if file.content_type not in ALLOWED_FILE_TYPES:
        raise HTTPException(status_code=400, detail=f"Unsupported file type: {file.content_type}. Allowed types are: {', '.join(ALLOWED_FILE_TYPES)}")
        
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully and is of an allowed type."}

            

              
                Copy
              
            
          

Pro robustnější kontrolu typu, zejména u obrázků, můžete zvážit použití knihoven, jako je Pillow, ke kontrole skutečného obsahu souboru, protože typy MIME mohou být někdy zfalšovány.

Zpracování chyb a zpětná vazba pro uživatele

Poskytujte uživateli jasné a proveditelné chybové zprávy. Použijte HTTPException FastAPI pro standardní chybové odpovědi HTTP.

• Soubor nebyl nalezen/chybí: Pokud nebyl odeslán požadovaný parametr souboru.
• Překročena velikost souboru: Jak je uvedeno v příkladu s limitem velikosti.
• Neplatný typ souboru: Jak je uvedeno v příkladu s omezením typu.
• Chyby serveru: Pro problémy během ukládání nebo zpracování souborů (např. plný disk, chyby oprávnění).

Bezpečnostní aspekty

Nahrávání souborů přináší bezpečnostní rizika:

• Škodlivé soubory: Nahrávání spustitelných souborů (.exe, .sh) nebo skriptů maskovaných jako jiné typy souborů. Vždy ověřte typy souborů a zvažte skenování nahraných souborů na malware.
• Path Traversal: Sanitizujte názvy souborů, abyste zabránili útočníkům v nahrávání souborů do nezamýšlených adresářů (např. pomocí názvů souborů jako ../../etc/passwd). UploadFile FastAPI zpracovává základní sanitizaci názvů souborů, ale je rozumné věnovat tomu zvláštní pozornost.
• Denial of Service: Implementujte limity velikosti souborů a potenciálně omezte rychlost na koncových bodech nahrávání.
• Cross-Site Scripting (XSS): Pokud zobrazujete názvy souborů nebo obsah souborů přímo na webové stránce, ujistěte se, že jsou správně ošetřeny, aby se zabránilo útokům XSS.

Osvědčený postup: Ukládejte nahrané soubory mimo kořenový adresář dokumentů vašeho webového serveru a obsluhujte je prostřednictvím vyhrazeného koncového bodu s příslušnými řízeními přístupu nebo použijte síť pro doručování obsahu (CDN).

Používání modelů Pydantic s nahráváním souborů

Zatímco UploadFile je primární typ pro soubory, můžete integrovat nahrávání souborů do modelů Pydantic pro složitější datové struktury. Nicméně, přímá pole pro nahrávání souborů ve standardních modelech Pydantic nejsou nativně podporována pro formuláře multipart. Místo toho obvykle obdržíte soubor jako samostatný parametr a poté jej potenciálně zpracujete do formátu, který lze uložit nebo ověřit modelem Pydantic.

Běžný vzor je mít model Pydantic pro metadata a poté přijímat soubor samostatně:

            from fastapi import FastAPI, File, UploadFile, Form
from pydantic import BaseModel
from typing import Optional

class UploadMetadata(BaseModel):
    title: str
    description: Optional[str] = None

app = FastAPI()

@app.post("/files/model_metadata/")
async def upload_with_metadata(
    metadata: str = Form(...), # Receive metadata as a JSON string
    file: UploadFile = File(...)
):
    import json
    try:
        metadata_obj = UploadMetadata(**json.loads(metadata))
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON format for metadata")
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Error parsing metadata: {e}")

    # Now you have metadata_obj and file
    # Proceed with saving file and using metadata
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())

    return {
        "message": "File uploaded successfully with metadata",
        "metadata": metadata_obj,
        "filename": file.filename
    }

            

              
                Copy
              
            
          

V tomto vzoru klient odesílá metadata jako řetězec JSON v poli formuláře (např. metadata) a soubor jako samostatnou multipart část. Server poté analyzuje řetězec JSON do objektu Pydantic.

Nahrávání velkých souborů a chunking

U velmi velkých souborů (např. gigabajty) mohou i streamování narážet na omezení webového serveru nebo na straně klienta. Pokročilejší technikou je chunked uploads, kde klient rozdělí soubor na menší části a nahrává je postupně nebo paralelně. Server poté tyto bloky znovu sestaví. To obvykle vyžaduje vlastní logiku na straně klienta a koncový bod serveru navržený pro správu bloků (např. identifikace bloků, dočasné úložiště a konečná montáž).

Zatímco FastAPI neposkytuje vestavěnou podporu pro chunked uploads iniciované klientem, můžete implementovat tuto logiku ve svých koncových bodech FastAPI. To zahrnuje vytvoření koncových bodů, které:

• Přijímají jednotlivé bloky souborů.
• Ukládají tyto bloky dočasně, případně s metadaty označujícími jejich pořadí a celkový počet bloků.
• Poskytují koncový bod nebo mechanismus k signalizaci, když byly nahrány všechny bloky, což spustí proces opětovného sestavení.

Toto je složitější úkol a často zahrnuje knihovny JavaScriptu na straně klienta.

Mezinárodní a globalizační aspekty

Při vytváření API pro globální publikum vyžadují nahrávání souborů zvláštní pozornost:

• Názvy souborů: Uživatelé po celém světě mohou používat znaky jiné než ASCII v názvech souborů (např. akcenty, ideogramy). Ujistěte se, že váš systém správně zpracovává a ukládá tyto názvy souborů. Kódování UTF-8 je obecně standardní, ale hluboká kompatibilita může vyžadovat pečlivé kódování/dekódování a sanitizaci.
• Jednotky velikosti souborů: Zatímco MB a GB jsou běžné, mějte na paměti, jak uživatelé vnímají velikosti souborů. Zobrazení limitů uživatelsky přívětivým způsobem je důležité.
• Typy obsahu: Uživatelé mohou nahrávat soubory s méně běžnými typy MIME. Ujistěte se, že váš seznam povolených typů je komplexní nebo dostatečně flexibilní pro váš případ použití.
• Regionální předpisy: Mějte na paměti zákony a předpisy o rezidenci dat v různých zemích. Ukládání nahraných souborů může vyžadovat soulad s těmito pravidly.
• Uživatelské rozhraní: Rozhraní na straně klienta pro nahrávání souborů by mělo být intuitivní a podporovat jazyk a národní prostředí uživatele.

Nástroje a knihovny pro testování

Testování koncových bodů nahrávání souborů je klíčové. Zde jsou některé běžné nástroje:

• Swagger UI (Interaktivní dokumentace API): FastAPI automaticky generuje dokumentaci Swagger UI. Můžete přímo testovat nahrávání souborů z rozhraní prohlížeče. Vyhledejte pole pro zadání souboru a klikněte na tlačítko „Vybrat soubor“.
• Postman: Populární nástroj pro vývoj a testování API. Chcete-li odeslat požadavek na nahrání souboru:
• Nastavte metodu požadavku na POST.
• Zadejte adresu URL koncového bodu API.
• Přejděte na kartu „Body“.
• Vyberte „form-data“ jako typ.
• V párech klíč-hodnota zadejte název parametru souboru (např. file).
• Změňte typ z „Text“ na „File“.
• Kliknutím na „Vybrat soubory“ vyberte soubor z místního systému.
• Pokud máte další pole formuláře, přidejte je podobně a ponechte jejich typ jako „Text“.
• Odešlete požadavek.
• cURL: Nástroj příkazového řádku pro vytváření požadavků HTTP.
• Pro jeden soubor: curl -X POST -F "file=@/path/to/your/local/file.txt" http://localhost:8000/files/
• Pro více souborů: curl -X POST -F "files=@/path/to/file1.txt" -F "files=@/path/to/file2.png" http://localhost:8000/files/multiple/
• Pro smíšená data: curl -X POST -F "description=My description" -F "files=@/path/to/file.txt" http://localhost:8000/files/mixed/
• Knihovna `requests` Pythonu: Pro programové testování.

            import requests

url = "http://localhost:8000/files/save/"
files = {'file': open('/path/to/your/local/file.txt', 'rb')}

response = requests.post(url, files=files)
print(response.json())

# For multiple files
url_multiple = "http://localhost:8000/files/multiple/"
files_multiple = {
    'files': [('file1.txt', open('/path/to/file1.txt', 'rb')),
              ('image.png', open('/path/to/image.png', 'rb'))]
}
response_multiple = requests.post(url_multiple, files=files_multiple)
print(response_multiple.json())

# For mixed data
url_mixed = "http://localhost:8000/files/mixed/"
data = {'description': 'Test description'}
files_mixed = {'files': open('/path/to/another_file.txt', 'rb')}
response_mixed = requests.post(url_mixed, data=data, files=files_mixed)
print(response_mixed.json())

            

              
                Copy
              
            
          

Závěr

FastAPI poskytuje výkonný, efektivní a intuitivní způsob, jak zpracovávat nahrávání souborů multipart. Využitím typu UploadFile a asynchronního programování mohou vývojáři vytvářet robustní API, která bezproblémově integrují možnosti zpracování souborů. Nezapomeňte upřednostnit zabezpečení, implementovat příslušné zpracování chyb a zvážit potřeby globální uživatelské základny řešením aspektů, jako je kódování názvů souborů a soulad s předpisy.

Ať už vytváříte jednoduchou službu pro sdílení obrázků nebo komplexní platformu pro zpracování dokumentů, zvládnutí funkcí nahrávání souborů FastAPI bude významným přínosem. Pokračujte v prozkoumávání jeho možností, implementujte osvědčené postupy a poskytujte výjimečné uživatelské prostředí pro své mezinárodní publikum.