Kaip jūs tvarkote formos duomenis ir failų įkėlimus?

Question

Accepted Answer

FastAPI tvarkytina HTML **formos duomenys** (`Form`) ir **failų įkėlimai** (`File`/`UploadFile`) — skiriasi nuo JSON kūno, nes jie naudoja skirtingus turinio tipus (`multipart/form-data`). Abu deklaruojami su specialiais parametrų tipais.

## Formos laukai

```python
from fastapi import Form

@app.post("/login")
def login(username: str = Form(), password: str = Form()):   # form fields, not JSON
    # data comes as application/x-www-form-urlencoded or multipart/form-data
    return {"username": username}
```

Naudokite `Form()` HTML formos laukams gauti (pvz., prisijungimo formai). Pastaba: maršrutas gali naudoti arba JSON kūną **arba** formos duomenis, bet ne abu kartu, nes jie yra skirtingų turinio tipų. (Reikalauja `python-multipart` instaliuotos.)

## Failų įkėlimai

```python
from fastapi import File, UploadFile

@app.post("/upload")
async def upload(file: UploadFile):                  # a single file
    contents = await file.read()                      # read the file's bytes
    file.filename                                      # original name
    file.content_type                                  # MIME type
    # save it:
    with open(f"uploads/{file.filename}", "wb") as f:
        f.write(contents)
    return {"filename": file.filename, "size": len(contents)}
```

`UploadFile` yra rekomenduojamas tipas — tai kauptas failas (dideli failai eina į diską, ne visas į atmintį), su asinchroniniais metodais (`read`, `write`, `seek`) ir metaduomenimis. Naudokite jį vietoj žaliųjų `bytes` viskas, išskyrus minūtūs failai.

## Keli failai ir forma + failas kartu

```python
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]):       # multiple files
    return [f.filename for f in files]

@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
    # combine form fields AND a file upload in one multipart request
    ...
```

## Patvirtinti įkėlimus (saugumas!)

```python
if file.content_type not in ["image/jpeg", "image/png"]:   # check type
    raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
```

## Kodėl tai svarbu

Formos duomenų ir failų įkėlimų tvarkymas yra dažna, praktinė poreikis — prisijungimo formos, profilio nuotraukų įkėlimai, dokumentų pateikimas ir failų apdorojimo API visgi jų reikalauja, ir tai veikia kitaip nei numatyti JSON kūnai, kuriuos naudoja FastAPI.

Supratimas apie `Form()` formos laukams ir ypač **`UploadFile`** įkėlimams (rekomenduojamas būdas, nes jis kaupa didelius failas diske, o ne visus į atmintį — svarbu tvarkant didelius failai be RAM išeikvojimo) yra būtinas šioms funkcijoms.

Lygiai taip pat svarbu yra **saugumo atsakomybė**, kuri ateina su įkėlimais: kadangi įkėlinti failai yra nepatikimas įvestis, jų tipo ir dydžio patvirtinimas, failų vardų dezinfekcija ir atsargumas, kaip juos saugote/pateikiate, yra esminis iš jų vengti pažeidžiamybes.

Žinojimas, kaip gauti formos laukus, tvarkyti vienus ir kelis failų įkėlimus, derinti formas su failais ir saugiai patvirtinti įkėlimus, yra praktinis žinojimas kurti tikrus API, kurie priimti vartotojų pateikiamą turinį.