Primera aplicación FastAPI
Esta sección, mediante un ejemplo completo, te guía para crear una aplicación FastAPI desde cero y comprender el significado de cada línea de código.
Aplicación mínima
Crea un archivo llamadomain.pyy agrega el siguiente código:
Ejemplo
# Paso 1: importar la clase FastAPI
# Paso 2: crear una instancia de la aplicación
app = FastAPI()
# Paso 3: definir el decorador de operación de ruta
# Paso 4: definir la función de operación de ruta
@app.get("/")
async def root():
# Paso 5: devolver el contenido de la respuesta
return {"message": "Hello World"}
Iniciar la aplicación:
$ uvicorn main:app --reload
Accede ahttp://127.0.0.1:8000y devuelve:
{"message": "Hello World"}
Desglose del código
1. Importar FastAPI
from fastapi import FastAPI
FastAPIEs una clase de Python que proporciona todas las funciones principales para tu API. Hereda directamente de Starlette, por lo que también puedes usar todas las funciones de Starlette.
2. Crear una instancia de la aplicación
app = FastAPI()
Crea una instancia de FastAPI; el nombre de la variable suele serapp. Esta instancia es el objeto principal de interacción para crear todas las API. A diferencia de Flask, FastAPI no necesita pasar__name__el parámetro.
3. Definir el decorador de operación de ruta
@app.get("/")
Esta línea de código le dice a FastAPI: cuando el usuario, a través del métodoGETacceda a la ruta raíz/, ejecute la función siguiente.
Esto involucra dos conceptos:
| Concepto | Descripción | Ejemplo |
|---|---|---|
| Ruta (Path) | En la URL, desde la primera// en adelante, también llamado "endpoint" o "ruta". | /items/foo |
| Operación (Operation) | Método HTTP, corresponde a diferentes semánticas de operación. | GET、POST、PUT、DELETE |
FastAPI admite decoradores para todos los métodos HTTP:
| Decorador | Método HTTP | Usos comunes |
|---|---|---|
@app.get() | GET | Obtener/leer datos |
@app.post() | POST | Crear nuevos datos |
@app.put() | PUT | Actualizar datos por completo |
@app.patch() | PATCH | Actualizar datos parcialmente |
@app.delete() | DELETE | Eliminar datos |
4. Definir la función de operación de ruta
async def root():
Esta es la función de operación de ruta; cada vez que FastAPI recibe una solicitudGET /, se invoca. El nombre de la función se puede elegir libremente, pero se recomienda usar un nombre significativo.
Puedes usarasync defo undefnormal para definir la función. FastAPI maneja automáticamente la diferencia entre ambos. Si no estás familiarizado con la programación asíncrona, usa undefnormal y listo; los capítulos posteriores explicarán la asincronía en detalle.
5. Devolver el contenido de la respuesta
return {"message": "Hello World"}
La función devuelve un diccionario, y FastAPI lo convierte automáticamente en una respuesta en formato JSON. Puedes devolverdict、list、str、intetc., FastAPI se encargará automáticamente de la conversión a JSON.
Agregar más rutas
A continuación, agregamos parámetros de ruta y parámetros de consulta para enriquecer la funcionalidad de la aplicación:
Ejemplo
app = FastAPI()
@app.get("/")
async def root():
"""Ruta raíz, devuelve un mensaje de bienvenida"""
return {"message": "Hello World"}
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
"""Obtiene un elemento según su ID, admite el parámetro de consulta opcional q"""
return {"item_id": item_id, "q": q}
Descripción de los parámetros de las nuevas rutas:
| Parámetro | Tipo | Origen | Descripción |
|---|---|---|---|
item_id | int | Parámetro de ruta | Se obtiene de la ruta de la URL; FastAPI convierte automáticamente la cadena a entero. |
q | str | None | Parámetro de consulta | Se obtiene de la parte?q=xxxde la URL; el valor predeterminado esNone, lo que indica que es opcional. |
Prueba de acceso:
# 访问根路径
GET http://127.0.0.1:8000/
响应: {"message": "Hello World"}
# 访问带路径参数的路由
GET http://127.0.0.1:8000/items/5
响应: {"item_id": 5, "q": null}
# 同时传递路径参数和查询参数
GET http://127.0.0.1:8000/items/5?q=ejemplo
响应: {"item_id": 5, "q": "ejemplo"}
Nota: el valor deitem_ides un entero5, no una cadena"5", esto es la funcionalidad de conversión de datos de las declaraciones de tipo de FastAPI. Si se pasa un valor no entero (por ejemplo,/items/foo), FastAPI devolverá un mensaje de error de validación claro.
Agregar solicitudes POST
A continuación, agregamos una ruta POST que utiliza un cuerpo de solicitud:
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: impuesto
@app.post("/items/")
async def create_item(item: Item):
"""Crea un nuevo producto y recibe un cuerpo de solicitud JSON"""
return item
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
"""Actualiza el producto especificado, usando a la vez parámetros de ruta y cuerpo de solicitud"""
return {"item_id": item_id, "item_name": item.name}
Aquí se usa elBaseModelde Pydantic para definir la estructura del cuerpo de la solicitud. FastAPI automáticamente:
- Convierte los datos JSON de la solicitud en un
Itemobjeto. - Valida los tipos de datos y los campos obligatorios.
- Muestra la estructura del cuerpo de la solicitud en la documentación de la API.
Pydantic es una dependencia central de FastAPI, utilizada para la validación y serialización de datos. Los capítulos posteriores explicarán su uso en detalle.
Reglas de reconocimiento de parámetros de FastAPI
FastAPI reconoce automáticamente el origen de los parámetros mediante las siguientes reglas:
| Origen del parámetro | Condición de reconocimiento | Ejemplo |
|---|---|---|
| Parámetro de ruta | El nombre del parámetro aparece en los{}Medio | item_idEn/items/{item_id}Medio |
| Parámetro de consulta | El parámetro es de un tipo único (int、str、booletc.) | q: str | None = None |
| Cuerpo de la solicitud | El tipo del parámetro es un modelo de Pydantic. | item: Item |
Puedes combinar estos tres tipos de parámetros en la misma función; FastAPI automáticamente obtendrá los datos de la ubicación correcta.
Resumen
Pasos clave para crear una aplicación FastAPI:
- Importar
FastAPI - Crear una instancia de la aplicación.
app = FastAPI() - Usar decoradores (como
@app.get()) para definir operaciones de ruta. - Definir funciones de operación de ruta, declarando parámetros con anotaciones de tipo.
- Usar
uvicorn main:app --reloadpara ejecutar el servidor de desarrollo.