FastAPI: campos del cuerpo de solicitud y modelos anidados
Dentro de los modelos Pydantic, puedes usarFieldpara declarar reglas de validación y metadatos para los campos, y también puedes anidar modelos para manejar estructuras de datos JSON complejas.
Declarar la validación de campos con Field
Al igual que en las funciones de operación de ruta se usaQuery、Pathde la misma manera que se declara la validación, dentro de los modelos Pydantic se usaFieldpara declarar la validación de campos:
Ejemplo
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100, description="Nombre del producto") # Obligatorio, de 1 a 100 caracteres
description: str | None = Field(default=None, max_length=300, description="Descripción del producto") # Opcional
price: float = Field(gt=0, description="Precio del producto") # Obligatorio, debe ser mayor que 0
tax: float | None = Field(default=None, ge=0, description="Impuesto") # Opcional, >= 0
@app.post("/items/")
async def create_item(item: Item):
return item
FieldParámetros de validación admitidos:
| Tipo de parámetro | Parámetro | Descripción |
|---|---|---|
| Validación de cadenas | min_length | Longitud mínima |
max_length | Longitud máxima | |
pattern | Coincidencia de expresión regular | |
| Validación numérica | gt | Mayor que |
ge | Mayor o igual que | |
lt | Menor que | |
le | Menor o igual que | |
| Metadatos | title | Título del campo |
description | Descripción del campo |
Nota
FielddesdepydanticImportar, y no desdefastapiimportar. Esto es diferente deQuery、Pathetc., desdefastapila importación es diferente.
Campos de tipo lista
Puedes declarar un campo como lista y especificar el tipo de sus elementos:
Ejemplo
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: list[str] = [] # Lista de cadenas, por defecto lista vacía
@app.post("/items/")
async def create_item(item: Item):
return item
Ejemplo de cuerpo de solicitud:
{
"name": "Foo",
"price": 42.0,
"tags": ["rock", "metal", "bar"]
}
Usar Set para eliminar duplicados
Si las etiquetas no deben repetirse, usa elsettipo:
Ejemplo
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set() # Elimina automáticamente etiquetas duplicadas
Incluso si la solicitud contiene etiquetas duplicadas, se eliminarán automáticamente en la respuesta.
Modelos anidados
El tipo de un campo de un modelo Pydantic puede ser otro modelo Pydantic, admitiendo anidamiento a cualquier profundidad:
Ejemplo
from pydantic import BaseModel, HttpUrl
app = FastAPI()
# Submodelo: Imagen
class Image(BaseModel):
url: HttpUrl # Valida automáticamente si es una URL válida
name: str
# Modelo principal: Producto, incluye el submodelo Imagen
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
image: Image | None = None # Información de imagen opcional
@app.post("/items/")
async def create_item(item: Item):
return item
La estructura correspondiente del cuerpo de solicitud:
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": ["rock", "metal", "bar"],
"image": {
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
}
}
Submodelos en listas
Puedes colocar submodelos en una lista:
Ejemplo
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None # Lista de imágenes
@app.post("/items/")
async def create_item(item: Item):
return item
El cuerpo de solicitud correspondiente:
{
"name": "Foo",
"price": 42.0,
"images": [
{"url": "http://example.com/baz.jpg", "name": "The Foo live"},
{"url": "http://example.com/dave.jpg", "name": "The Baz"}
]
}
Modelos profundamente anidados
Puedes definir estructuras anidadas de cualquier profundidad:
Ejemplo
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
images: list[Image] | None = None
class Offer(BaseModel):
name: str
description: str | None = None
price: float
items: list[Item] # Offer contiene varios Item, e Item contiene varias Image
@app.post("/offers/")
async def create_offer(offer: Offer):
return offer
Cuerpo de solicitud de lista pura
Si la capa más externa del cuerpo de solicitud es un array JSON, puedes declarar el tipo lista directamente en los parámetros de la función:
Ejemplo
from pydantic import BaseModel, HttpUrl
app = FastAPI()
class Image(BaseModel):
url: HttpUrl
name: str
# El cuerpo de solicitud es directamente una lista de Image
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
return images
Cuerpo de solicitud compuesto por un dict arbitrario
Cuando necesitas recibir datos de diccionario cuyas claves no son fijas, puedes declarar undicttipo de cuerpo de solicitud:
Ejemplo
app = FastAPI()
# Recibe un diccionario con claves int y valores float
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
return weights
Ejemplo de cuerpo de solicitud:
{
"1": 0.5,
"2": 1.5,
"3": 2.0
}
JSON solo admite claves de tipo cadena, pero Pydantic convierte automáticamente las claves de cadena al tipo declarado (como en este ejemplo,
int)。
Resumen
- Usando Pydantic
Fieldpara agregar validación y metadatos a los campos del modelo list[str]、set[str]Los tipos de colección, etc., pueden declarar campos de lista/conjunto- Los modelos pueden anidarse, admitiendo estructuras JSON de cualquier profundidad.
HttpUrly otros tipos especiales validan automáticamente el formato.- Las listas puras y los diccionarios arbitrarios también pueden usarse como tipo de cuerpo de solicitud.