FastAPI Parámetros de ruta

Los parámetros de ruta son partes dinámicas de la URL, que se declaran{}con llaves. FastAPI pasa automáticamente los parámetros de ruta a la función de operación de ruta, y realiza la conversión de datos y la validación según las anotaciones de tipo.


Uso básico

Declara los parámetros de ruta usando la sintaxis de cadenas formateadas de Python:

Ejemplo

from fastapi import FastAPI

app = FastAPI()

# {item_id} es el parámetro de ruta
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Accede ahttp://127.0.0.1:8000/items/5, devuelve:

{"item_id": 5}

Nota que el valor devueltoitem_ides un entero5, no una cadena"5". FastAPI, mediante la anotación de tipoitem_id: intconvierte automáticamente la cadena de la URL en un entero.


Conversión de datos

Cuando declaras el tipo comoint, FastAPI realiza automáticamente la conversión de tipo:

# 传入整数,正常工作
GET /items/3       -> {"item_id": 3}

# 传入非整数,返回校验错误
GET /items/foo     -> 错误:Input should be a valid integer

# 传入浮点数,同样报错
GET /items/4.2     -> 错误:Input should be a valid integer

Al acceder ahttp://127.0.0.1:8000/items/foo, FastAPI devuelve el mensaje de error de validación:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "item_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

Los mensajes de error de validación de FastAPI son muy claros, indican la ubicación específica del error (loc), el tipo de error (type) y la descripción del error (msg). Esto es muy útil al depurar.


Tipos de parámetros de ruta

Además deint, también puedes usar otros tipos estándar de Python:

TipoDescripciónEjemplo de URL
strCadena (tipo predeterminado)/items/foo
intEntero/items/5
floatNúmero de punto flotante/items/5.5
boolValor booleano/items/true
uuid.UUIDUUID/items/3fa85f64-5717-4562-b3fc-2c963f66afa6

El orden de las rutas es importante

Cuando varias rutas pueden coincidir con la misma URL, el orden de definición determina el resultado de la coincidencia. FastAPI compara en orden según la definición de las rutas, y se ejecutará la primera ruta que coincida.

Ejemplo

from fastapi import FastAPI

app = FastAPI()

# Debe definirse antes de /users/{user_id}
@app.get("/users/me")
async def read_user_me():
    """Obtener información del usuario actual"""
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    """Obtener información del usuario según el ID"""
    return {"user_id": user_id}

Si se pone/users/medespués de/users/{user_id}la ruta dinámica, al acceder a/users/meFastAPI considerará que"me"Síuser_ides el valor de, coincidiendo así con la función incorrecta.

Las rutas de ruta fija deben colocarse antes de las rutas con parámetros de ruta dinámicos; de lo contrario, el parámetro dinámico "se tragará" el valor de la ruta fija.


Parámetros de ruta con valores predefinidos (Enum)

Cuando necesites restringir el parámetro de ruta a solo unos pocos valores fijos, puedes usar elEnumtipo de Python:

Ejemplo

from enum import Enum
from fastapi import FastAPI


# Crea una clase de enumeración, hereda de str y Enum
class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    # Se puede comparar con los miembros de la enumeración
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Puntos clave de la clase de enumeración:

Punto claveDescripción
HeredarstrHace que la documentación de la API reconozca el tipo de valor como cadena, asegurando una representación correcta
HeredarEnumCrea el tipo de enumeración, limita los valores opcionales
model_name.valueObtener el valor real del miembro de la enumeración (por ejemplo,"alexnet")

Accede ahttp://127.0.0.1:8000/models/alexnet, devuelve:

{"model_name": "alexnet", "message": "Deep Learning FTW!"}

Si se pasa un valor no predefinido (por ejemplo,/models/foobar), FastAPI devolverá un error de validación, indicando que los valores opcionales sonalexnet、resnet、lenet。


Parámetros de ruta que contienen rutas

Cuando necesites que el propio parámetro de ruta contenga una ruta (como una ruta de archivo), usa el conversor de rutas de Starlette:

Ejemplo

from fastapi import FastAPI

app = FastAPI()

# :path indica que este parámetro puede coincidir con rutas que contienen barras
@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Accede ahttp://127.0.0.1:8000/files/home/johndoe/myfile.txt, devuelve:

{"file_path": "home/johndoe/myfile.txt"}

Nota que en la URL/files/y/home/entre aparecerá una doble barra//, esto es normal, porque el parámetro de ruta/comienza con.


Resumen

Mediante la declaración de tipos estándar de Python, los parámetros de ruta de FastAPI pueden obtener simultáneamente:

  • Conversión de datos: la cadena en la URL se convierte automáticamente al tipo declarado
  • Validación de datos: devuelve mensajes de error claros cuando el tipo no coincide
  • Documentación automática: el tipo y las restricciones de los parámetros de ruta aparecen automáticamente en la documentación de la API
  • Compatibilidad con el editor: las anotaciones de tipo te permiten obtener autocompletado en el editor
Otras extensiones