Modelos de Solicitud y Respuesta
FastAPI utiliza modelos Pydantic 2 para validar solicitudes y dar forma a las respuestas en el límite HTTP.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class ItemCreate(BaseModel):
name: str = Field(min_length=1)
price: float = Field(gt=0)
class ItemRead(BaseModel):
id: int
name: str
price: float
@app.post('/items', response_model=ItemRead, status_code=201)
def create_item(payload: ItemCreate) -> ItemRead:
return ItemRead(id=1, **payload.model_dump())Cuándo usar esto:
- Los cuerpos JSON necesitan reglas de campo
- Las respuestas deben ocultar secretos
- OpenAPI debe coincidir con el tiempo de ejecución
Ejemplo de Trabajo
from datetime import datetime
from fastapi import FastAPI, Query
from pydantic import BaseModel, ConfigDict, Field, field_validator
app = FastAPI()
class Page(BaseModel):
page: int = Field(1, ge=1)
size: int = Field(20, ge=1, le=100)
class ArticleIn(BaseModel):
title: str
tags: list[str] = Field(default_factory=list)
@field_validator('tags')
@classmethod
def norm(cls, v):
return sorted({t.strip().lower() for t in v})
class ArticleOut(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
title: str
tags: list[str]
created_at: datetime
@app.get('/articles', response_model=list[ArticleOut])
def list_articles(p: Page = Query()) -> list[ArticleOut]:
return [ArticleOut(id=1, title='Demo', tags=['api'], created_at=datetime.now())]Lo que esto demuestra:
- Modelos de entrada/salida separados
- Normalización con
field_validator from_attributespara ORM
Análisis Profundo
Cómo Funciona
- FastAPI analiza el JSON en modelos Pydantic antes de que se ejecute tu función.
response_modelfiltra los campos de salida para los clientes y OpenAPI.- Usa
model_dump(mode='json')para la serialización explícita.
Notas de Python
# Rechazar claves desconocidas en el límite
class StrictIn(BaseModel):
model_config = ConfigDict(extra='forbid')Errores Comunes
- Validación del límite omitida - Datos inválidos se propagan a la base de datos. Solución: Valida con Pydantic en las rutas y formularios web.
- Fuga de excepciones internas - Trazas de pila llegan a los clientes. Solución: Registra manejadores de excepciones y devuelve mensajes seguros.
- Bloqueo del bucle de eventos - Las rutas asíncronas llaman a E/S síncrona. Solución: Usa controladores asíncronos o
run_in_threadpoolpara código bloqueante. - Módulos "Dios" - Toda la lógica en un solo archivo. Solución: Divide routers, servicios y repositorios por dominio.
- Tiempos de espera faltantes - Las llamadas externas colgadas detienen los workers. Solución: Establece tiempos de espera en los clientes HTTP y de bases de datos.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Patrón nativo del Framework X | Ya estás estandarizado en esa pila | Necesitas APIs asíncronas "OpenAPI-first" |
| Funciones Serverless | Cargas de trabajo con ráfagas de bajo tráfico | Conexiones de larga duración o WebSockets |
| GraphQL | Los clientes necesitan selección flexible de campos | CRUD simple con caché robusta |
Preguntas Frecuentes
¿Cuándo debo usar modelos de solicitud y respuesta?
Utilízalo cuando los patrones de esta página coincidan con tu integración o restricción de diseño.
¿Cuál es el error más común con los modelos de solicitud y respuesta?
Omitir la validación o el manejo de errores en el límite y trasladar la complejidad a los manejadores.
¿Cómo pruebo los modelos de solicitud y respuesta?
Usa clientes de prueba del framework con anulaciones de dependencias y verifica los códigos de estado y los cuerpos JSON.
¿Los modelos de solicitud y respuesta funcionan con código asíncrono?
Sí, cuando usas controladores compatibles con asíncronos y evitas llamadas bloqueantes en rutas asíncronas.
¿Cómo interactúan los modelos de solicitud y respuesta con Pydantic 2?
Los modelos validan en el borde; los servicios deben confiar en los objetos tipados en el interior.
¿Qué pertenece a una capa de servicio y qué a las rutas?
Las rutas analizan y autorizan; los servicios implementan reglas de negocio y persistencia.
¿Cómo manejo los errores de manera consistente?
Mapea los errores de dominio a excepciones HTTP o a un esquema de error compartido.
¿Debo fijar las versiones de las dependencias?
Sí, bloquea FastAPI, Django, Flask y los controladores en las imágenes de producción.
¿Cómo documento esto para los clientes?
Exporta OpenAPI y mantén los modelos de respuesta alineados con los payloads reales.
¿Dónde puedo aprender más en este cookbook?
Sigue los enlaces relacionados al final de esta página.
Relacionados
- Inyección de Dependencias - Comparte dependencias de paginación
- Fundamentos de FastAPI - Primeras rutas
- Pruebas de FastAPI - Asertos 422
- Autenticación y Autorización - Modelos de seguridad
Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.