Datos de formulario en FastAPI

Cuando el cliente, a través de un formulario HTML (application/x-www-form-urlencoded) envía los datos, es necesario usarFormpara recibir los campos del formulario, y noBaseModel。

Instalar python-multipart

Antes de usar las funciones de formulario, primero debes instalarpython-multipart：

pip install python-multipart

Recibir datos de formulario

UsaFormpara declarar los campos de formulario:

Ejemplo

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(
    username: str = Form(),      # Campo de formulario obligatorio
    password: str = Form(),      # Campo de formulario obligatorio
):
    return {"username": username}

Diferencia entre los campos de formulario y el cuerpo de solicitud JSON

Elemento de comparaciónCuerpo de solicitud JSONDatos de formulario
Content-Typeapplication/jsonapplication/x-www-form-urlencoded
Método de declaraciónPydantic BaseModelForm()
Estructura de datosAdmite objetos anidados y arreglosPares clave-valor planos
Escenarios de aplicaciónInterfaz de API (frontend y backend separados)Envío de formularios HTML

Los datos de formulario se envían como "campos", no como JSON. Por lo tanto, no se puedeFormdeclarar el parámetro como un modelo de Pydantic. Los campos de formulario y el cuerpo de solicitud JSON no se pueden usar simultáneamente en la misma ruta.

Campos de formulario opcionales

Al igual que los parámetros de consulta, los campos de formulario con valores predeterminados son opcionales:

Ejemplo

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/items/")
async def create_item(
    name: str = Form(...),                    # Obligatorio
    description: str | None = Form(None),     # Opcional, predeterminado None
    price: float = Form(..., gt=0),           # Obligatorio, debe ser mayor que 0
):
    return {"name": name, "description": description, "price": price}

Probar con formularios HTML

Puedes crear una página HTML para probar el envío del formulario:

Ejemplo

<form action="http://localhost:8000/items/" method="post">
    <label for="name">Name:</label>
    <input type="text" id="name" name="name" required>
    <br>
    <label for="description">Description:</label>
    <textarea id="description" name="description"></textarea>
    <br>
    <label for="price">Price:</label>
    <input type="number" id="price" name="price" required min="0">
    <br>
    <button type="submit">Submit</button>
</form>

Validación y documentación de los datos de formulario

Los campos declarados conFormFastAPI valida automáticamente los datos y los muestra en la documentación de la API:

Resumen

  • UsaFormpara recibir los datos enviados por formularios HTML
  • Los datos de formulario no son JSON, no se puedenBaseModelmezclar con el cuerpo de solicitud.
  • Form()Declarar campos obligatorios,Form(None)declarar campos opcionales.
  • Es necesario instalarpython-multipartPaquete
  • Los campos de formulario admiten las mismas reglas de validación que los parámetros de consulta (min_length、gtetc.)
Otras extensiones