¿Cómo manejas datos de formularios y cargas de archivos?

Question

Accepted Answer

FastAPI maneja **datos de formularios HTML** (`Form`) y **cargas de archivos** (`File`/`UploadFile`) — distintos de cuerpos JSON, ya que usan tipos de contenido diferentes (`multipart/form-data`). Ambos se declaran con tipos de parámetros especiales.

## Campos de formulario

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

Usa `Form()` para recibir campos de formulario HTML (por ejemplo, un formulario de inicio de sesión). Nota: una ruta puede usar un cuerpo JSON **o** datos de formulario, no ambos, ya que son tipos de contenido diferentes. (Requiere `python-multipart` instalado.)

## Cargas de archivos

```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` es el tipo recomendado — es un archivo agrupado (los archivos grandes van al disco, no todo en memoria), con métodos async (`read`, `write`, `seek`) y metadatos. Úsalo en lugar de `bytes` sin procesar para todo excepto archivos muy pequeños.

## Múltiples archivos y formulario + archivo 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
    ...
```

## Valida cargas (¡seguridad!)

```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 qué es importante

Manejar datos de formularios y cargas de archivos es una necesidad común y práctica — formularios de inicio de sesión, cargas de fotos de perfil, envíos de documentos y API de procesamiento de archivos todos lo requieren, y funciona de manera diferente a los cuerpos JSON que FastAPI usa por defecto.

Comprender `Form()` para campos de formulario y especialmente **`UploadFile`** para cargas (el enfoque recomendado, ya que agrupa archivos grandes en el disco en lugar de cargar todo en memoria — importante para manejar archivos grandes sin agotar la RAM) es necesario para estas características.

Igualmente importante es la **responsabilidad de seguridad** que viene con las cargas: dado que los archivos cargados son entrada no confiable, validar su tipo y tamaño, desinfectar nombres de archivos y tener cuidado en cómo los almacenas/sirves es esencial para evitar vulnerabilidades.

Saber cómo recibir campos de formulario, manejar cargas de archivos simples y múltiples, combinar formularios con archivos y validar cargas de forma segura es conocimiento práctico para construir API del mundo real que acepten contenido enviado por el usuario.