Πώς χειρίζεστε τα δεδομένα φόρμας και τις μεταφορτώσεις αρχείων;

Question

Accepted Answer

Το FastAPI χειρίζεται **δεδομένα φόρμας HTML** (`Form`) και **μεταφορτώσεις αρχείων** (`File`/`UploadFile`) — ξεχωριστά από σώματα JSON, επειδή χρησιμοποιούν διαφορετικούς τύπους περιεχομένου (`multipart/form-data`). Και τα δύο δηλώνονται με ειδικούς τύπους παραμέτρων.

## Πεδία φόρμας

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

Χρησιμοποιήστε `Form()` για να λάβετε πεδία φόρμας HTML (π.χ. φόρμα σύνδεσης). Σημείωση: ένα route μπορεί να χρησιμοποιεί είτε ένα σώμα JSON **ή** δεδομένα φόρμας, όχι και τα δύο, επειδή είναι διαφορετικοί τύποι περιεχομένου. (Απαιτεί `python-multipart` εγκατεστημένο.)

## Μεταφορτώσεις αρχείων

```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` είναι ο συνιστώμενος τύπος — είναι ένα spooled αρχείο (τα μεγάλα αρχεία πηγαίνουν στον δίσκο, όχι όλα στη μνήμη), με async μεθόδους (`read`, `write`, `seek`) και μεταδεδομένα. Χρησιμοποιήστε το αντί για raw `bytes` για ό,τι εκτός από πολύ μικρά αρχεία.

## Πολλαπλά αρχεία και φόρμα + αρχείο μαζί

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

## Επαληθεύστε τις μεταφορτώσεις (ασφάλεια!)

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

## Γιατί έχει σημασία

Η χειρισμός δεδομένων φόρμας και μεταφορτώσεων αρχείων είναι μια κοινή, πρακτική ανάγκη — φόρμες σύνδεσης, μεταφορτώσεις εικόνων προφίλ, υποβολές εγγράφων και API επεξεργασίας αρχείων όλα απαιτούν αυτό, και λειτουργεί διαφορετικά από τα σώματα JSON που χρησιμοποιεί το FastAPI από προεπιλογή.

Η κατανόηση του `Form()` για πεδία φόρμας και ιδιαίτερα του **`UploadFile`** για μεταφορτώσεις (η συνιστώμενη προσέγγιση, επειδή spools τα μεγάλα αρχεία στον δίσκο αντί να φορτώνει όλα στη μνήμη — σημαντικό για τη διαχείριση μεγάλων αρχείων χωρίς να εξαντληθεί η RAM) είναι απαραίτητη για αυτές τις δυνατότητες.

Εξίσου σημαντική είναι η **ευθύνη ασφάλειας** που συνοδεύει τις μεταφορτώσεις: επειδή τα μεταφορτωθέντα αρχεία είναι έμπιστη είσοδος, η επαλήθευση του τύπου και του μεγέθους τους, ο καθαρισμός ονομάτων αρχείων και ο προσεκτικός χειρισμός του τρόπου αποθήκευσης/υπηρεσίας τους είναι απαραίτητος για την αποφυγή ευπαθειών.

Η γνώση του τρόπου λήψης πεδίων φόρμας, χειρισμού μεμονωμένων και πολλαπλών μεταφορτώσεων αρχείων, συνδυασμού φορμών με αρχεία και ασφαλούς επαλήθευσης μεταφορτώσεων είναι πρακτική γνώση για τη δημιουργία API πραγματικού κόσμου που δέχονται περιεχόμενο που υπέβαλε ο χρήστης.