Cuerpo de solicitud FastAPI
El cuerpo de solicitud son los datos que el cliente envía a la API. Cuando necesitas recibir datos JSON del cliente, usa el cuerpo de solicitud para transmitirlos. FastAPI utiliza modelos Pydantic para declarar la estructura del cuerpo de solicitud y automáticamente realiza la validación de datos, la conversión y la generación de documentación.
Diferencia entre el cuerpo de solicitud y los parámetros de consulta
| Método de transmisión de datos | Ubicación | Escenario de aplicación | Método HTTP |
|---|---|---|---|
| Parámetro de ruta | Ruta de URL/items/5 | Identificar recursos | GET, PUT, DELETE, etc. |
| Parámetro de consulta | En la URL?key=value | Parámetros opcionales como filtrado, paginación, etc. | Principalmente GET |
| Cuerpo de solicitud | Datos JSON de la solicitud | Enviar datos complejos | POST、PUT、PATCH |
Para enviar datos se debe usar
POST(el más común),PUT、DELETEoPATCH. Aunque FastAPI técnicamente admite que las solicitudes GET lleven un cuerpo de solicitud, esto no cumple con la especificación HTTP, y Swagger UI no mostrará documentación del cuerpo de solicitud para solicitudes GET.
Declarar el cuerpo de solicitud con modelos Pydantic
1. Importar BaseModel
from pydantic import BaseModel
2. Crear el modelo de datos
Define una clase que herede deBaseModella clase, usando tipos estándar de Python para declarar todos los atributos:
Ejemplo
from pydantic import BaseModel
app = FastAPI()
# Definir el modelo de datos del cuerpo de la solicitud
class Item(BaseModel):
name: str # Obligatorio: Nombre del producto
description: str | None = None # Opcional: Descripción del producto
price: float # Obligatorio: Precio del producto
tax: float | None = None # Opcional: impuestos
@app.post("/items/")
async def create_item(item: Item):
return item
Las reglas sobre si un atributo es obligatorio son las mismas que para los parámetros de consulta:
- Los atributos con valor predeterminado son opcionales (como
description、tax) - Los atributos sin valor predeterminado son obligatorios (como
name、price)
Los siguientes JSON son cuerpos de solicitud válidos:
// 包含所有字段
{
"name": "Foo",
"description": "可选描述",
"price": 45.2,
"tax": 3.5
}
// 省略可选字段
{
"name": "Foo",
"price": 45.2
}
Procesamiento del cuerpo de solicitud por FastAPI
Solo con declaraciones de tipos de Python, FastAPI puede realizar automáticamente el siguiente trabajo:
| Función | Descripción |
|---|---|
| Leer el cuerpo de solicitud | Lee los datos de la solicitud en formato JSON |
| Conversión de tipos | Convierte los datos al tipo declarado (por ejemplo, de cadena a número de coma flotante) |
| Validación de datos | Valida los datos y devuelve mensajes de error claros cuando son inválidos |
| Asignación de parámetros | Asigna los datos validados a los parámetros de la función, obteniendo autocompletado del editor |
| Generación de documentación | Genera automáticamente un JSON Schema que aparece en la documentación de la API |
Usar atributos del modelo
Dentro de la función de operación de ruta, puedes acceder a todos los atributos del modelo como si manipularas un objeto Python normal:
Ejemplo
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.post("/items/")
async def create_item(item: Item):
# Acceder directamente a los atributos del modelo
item_dict = item.model_dump() # Métodos de serialización de Pydantic v2
if item.tax:
# Calcular el precio con impuestos
price_with_tax = item.price + item.tax
item_dict.update({"price_with_tax": price_with_tax})
return item_dict
Pydantic v2 usa
model_dump()en lugar deldict()método de v1 para serializar los datos del modelo.model_dump()Devuelve un diccionario que contiene todos los campos del modelo.
Cuerpo de solicitud + parámetros de ruta
Se pueden declarar simultáneamente parámetros de ruta y cuerpo de solicitud; FastAPI obtiene automáticamente los datos de la ubicación correcta:
Ejemplo
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Usar a la vez parámetros de ruta y cuerpo de solicitud
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
return {"item_id": item_id, "item_name": item.name}
Reglas de reconocimiento de FastAPI:
item_idSi está en la ruta{item_id}dentro de `{}` -> parámetro de rutaitemel tipo es un modelo Pydantic -> cuerpo de solicitud
Cuerpo de solicitud + parámetros de ruta + parámetros de consulta
Los tres se pueden usar simultáneamente:
Ejemplo
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Usar simultáneamente parámetros de ruta, parámetros de consulta y cuerpo de solicitud
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
result = {"item_id": item_id, **item.model_dump()}
if q:
result.update({"q": q})
return result
Reglas completas de reconocimiento de parámetros de FastAPI:
| Condición de reconocimiento | Origen del parámetro |
|---|---|
Si el nombre del parámetro está en la ruta{}se declara en `{}` | Parámetro de ruta |
El parámetro es de un solo tipo (int、str、booletc.) | Parámetro de consulta |
| El tipo de parámetro es un modelo Pydantic | Cuerpo de solicitud |
Resumen
Puntos clave del cuerpo de solicitud:
- Usa el
BaseModelde Pydantic para definir la estructura del cuerpo de solicitud. - Los campos con valor predeterminado son opcionales; los campos sin valor predeterminado son obligatorios.
- El cuerpo de solicitud se puede usar junto con parámetros de ruta y parámetros de consulta.
- FastAPI realiza automáticamente la validación de datos, la conversión de tipos y la generación de documentación.
- Pydantic v2 usa
model_dump()para serializar.