Form verilerini ve dosya yüklemelerini nasıl işlersiniz?

Question

Accepted Answer

FastAPI, HTML **form verilerini** (`Form`) ve **dosya yüklemelerini** (`File`/`UploadFile`) işler — JSON gövdelerinden farklı olarak, çünkü farklı içerik türleri kullanırlar (`multipart/form-data`). Her ikisi de özel parametre türleriyle bildirilir.

## Form alanları

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

HTML form alanlarını almak için `Form()` kullanın (örneğin bir giriş formu). Not: bir rota JSON gövdesi **veya** form verilerini kullanabilir, ikisini birlikte değil, çünkü bunlar farklı içerik türleridir. (`python-multipart` yüklü olması gerekir.)

## Dosya yüklemeleri

```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` önerilen türdür — bu bir spooled dosyadır (büyük dosyalar diske gider, tümü bellekte değil), async metodlarıyla (`read`, `write`, `seek`) ve meta verilerle. Küçük dosyalar dışında her şey için ham `bytes` yerine bunu kullanın.

## Birden fazla dosya ve form + dosya birlikte

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

## Yüklemeleri doğrulayın (güvenlik!)

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

## Neden önemli

Form verilerini ve dosya yüklemelerini işlemek yaygın, pratik bir gerekliliktir — giriş formları, profil resmi yüklemeleri, belge gönderimleri ve dosya işleme API'leri hepsi bunu gerektirir ve FastAPI'nin varsayılan olarak kullandığı JSON gövdelerinden farklı çalışır.

`Form()` için form alanlarını ve özellikle **`UploadFile`** için yüklemeleri anlamak (önerilen yaklaşım, çünkü büyük dosyaları diske aktarır, tümünü belleğe yüklemez — büyük dosyaları RAM'i tüketmeden işlemek için önemli) bu özellikler için gereklidir.

Eşit derecede önemli, yükleme ile gelen **güvenlik sorumluluğudur**: yüklenmiş dosyalar güvenilmeyen giriş olduğundan, bunların türünü ve boyutunu doğrulamak, dosya adlarını temizlemek ve bunları nasıl saklayıp/sunacağınız hakkında dikkatli olmak, güvenlik açıklarını önlemek için gereklidir.

Form alanlarını nasıl alacağınızı, tek ve birden fazla dosya yüklemelerini nasıl işleyeceğinizi, formları dosyalarla nasıl birleştireceğinizi ve yüklemeleri güvenli şekilde nasıl doğrulayacağınızı bilmek, kullanıcı tarafından gönderilen içeriği kabul eden gerçek dünya API'leri oluşturmak için pratik bilgidir.