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 datosUbicaciónEscenario de aplicaciónMétodo HTTP
Parámetro de rutaRuta de URL/items/5Identificar recursosGET, PUT, DELETE, etc.
Parámetro de consultaEn la URL?key=valueParámetros opcionales como filtrado, paginación, etc.Principalmente GET
Cuerpo de solicitudDatos JSON de la solicitudEnviar datos complejosPOST、PUT、PATCH

Para enviar datos se debe usarPOST(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 fastapi import FastAPI
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 (comodescription、tax)
  • Los atributos sin valor predeterminado son obligatorios (comoname、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ónDescripción
Leer el cuerpo de solicitudLee los datos de la solicitud en formato JSON
Conversión de tiposConvierte los datos al tipo declarado (por ejemplo, de cadena a número de coma flotante)
Validación de datosValida los datos y devuelve mensajes de error claros cuando son inválidos
Asignación de parámetrosAsigna los datos validados a los parámetros de la función, obteniendo autocompletado del editor
Generación de documentaciónGenera 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 fastapi import FastAPI
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 usamodel_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 fastapi import FastAPI
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 ruta
  • itemel 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 fastapi import FastAPI
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 reconocimientoOrigen 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 PydanticCuerpo de solicitud

Resumen

Puntos clave del cuerpo de solicitud:

  • Usa elBaseModelde 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 usamodel_dump()para serializar.
Otras extensiones