Como você manipula dados de formulário e uploads de arquivo?

Question

Accepted Answer

FastAPI manipula **dados de formulário** HTML (`Form`) e **uploads de arquivo** (`File`/`UploadFile`) — distintos de corpos JSON, já que usam tipos de conteúdo diferentes (`multipart/form-data`). Ambos são declarados com tipos de parâmetros especiais.

## Campos de formulário

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

Use `Form()` para receber campos de formulário HTML (por exemplo, um formulário de login). Nota: uma rota pode usar um corpo JSON **ou** dados de formulário, não ambos, pois são tipos de conteúdo diferentes. (Requer `python-multipart` instalado.)

## Upload de arquivos

```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` é o tipo recomendado — é um arquivo em buffer (arquivos grandes vão para o disco, não tudo na memória), com métodos async (`read`, `write`, `seek`) e metadados. Use-o em vez de `bytes` brutos para qualquer coisa além de arquivos muito pequenos.

## Múltiplos arquivos e formulário + arquivo juntos

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

## Validar uploads (segurança!)

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

## Por que isso importa

Manipular dados de formulário e uploads de arquivo é uma necessidade comum e prática — formulários de login, uploads de foto de perfil, envios de documentos e APIs de processamento de arquivos todos requerem isso, e funciona de forma diferente dos corpos JSON que FastAPI usa por padrão.

Compreender `Form()` para campos de formulário e especialmente **`UploadFile`** para uploads (a abordagem recomendada, pois bufferiza arquivos grandes no disco em vez de carregar tudo na memória — importante para lidar com arquivos grandes sem esgotar a RAM) é necessário para essas funcionalidades.
Igualmente importante é a **responsabilidade de segurança** que vem com uploads: como arquivos enviados são entrada não confiável, validar seu tipo e tamanho, sanitizar nomes de arquivo e ter cuidado com a forma como você os armazena/distribui é essencial para evitar vulnerabilidades.

Saber como receber campos de formulário, lidar com uploads de arquivo único e múltiplo, combinar formulários com arquivos e validar uploads com segurança é conhecimento prático para construir APIs do mundo real que aceitem conteúdo enviado pelo usuário.