Miten käsittelet lomakkeen tietoja ja tiedoston latauksia?

Question

Accepted Answer

FastAPI käsittelee **HTML-lomakkeen tietoja** (`Form`) ja **tiedoston latauksia** (`File`/`UploadFile`) — jotka eroavat JSON-rungosta, koska ne käyttävät erilaisia sisältötyyppejä (`multipart/form-data`). Molemmat ilmoitetaan erityisillä parametrityypeillä.

## Lomakkeen kentät

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

Käytä `Form()`-funktiota HTML-lomakkeen kenttien vastaanottamiseen (esim. kirjautumislomake). Huomio: reitti voi käyttää joko JSON-runkoa **tai** lomakkeen tietoja, ei molempia, koska ne ovat erilaisia sisältötyyppejä. (Vaatii `python-multipart`-asennuksen.)

## Tiedoston lataukset

```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` on suositeltu tyyppi — se on väliaikainen tiedosto (suuret tiedostot menevät levylle, ei kaikki muistiin), async-metodeilla (`read`, `write`, `seek`) ja metadatalla. Käytä sitä raa'an `bytes`-datan sijaan kaikkeen paitsi pieniin tiedostoihin.

## Useat tiedostot ja lomake + tiedosto yhdessä

```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
    ...
```

## Vahvista lataukset (turvallisuus!)

```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
```

## Miksi sillä on merkitystä

Lomakkeen tietojen ja tiedoston latausten käsittely on yleinen, käytännöllinen tarve — kirjautumislomakkeet, profiilikuvien lataukset, asiakirjojen jättäminen ja tiedoston käsittely-API:t kaikki vaativat sitä, ja se toimii eri tavalla kuin JSON-runko, jota FastAPI käyttää oletuksena.

Ymmärrys `Form()`-funktiosta lomakkeen kentille ja erityisesti **`UploadFile`**-funktiosta latauksia varten (suositeltu lähestymistapa, koska se väliaikaistaa suuret tiedostot levylle kaiken muistiin lataamisen sijaan — tärkeä suurien tiedostojen käsittelylle ilman RAM:n ehtymistä) on välttämätöntä näille ominaisuuksille.

Yhtä tärkeä on **turvallisuuden vastuu**, joka tulee latausten mukana: koska ladatut tiedostot ovat epäluotettavaa syötettä, niiden tyypin ja koon validoiminen, tiedostonimien puhdistaminen ja varovaisuus siinä, kuinka niitä tallennat/jaelet, on olennaista haavoittuvuuksien välttämiseksi.

Tietäminen, kuinka vastaanottaa lomakkeen kenttiä, käsitellä yksittäisiä ja useita tiedoston latauksia, yhdistää lomakkeita tiedostoihin ja vahvistaa lataukset turvallisesti, on käytännöllistä tietoa todellisen maailman API:en rakentamiseen, jotka hyväksyvät käyttäjän lähettämää sisältöä.