Habilidad Experta de FastAPI

Generación y revisión idiomática de servicios FastAPI - una Habilidad de Agente para Python 3.14, FastAPI 0.115+ y Pydantic 2.

Qué Hace Esta Habilidad

Produce una lista de verificación para API desplegable: estructura src/, pyproject.toml con uv, módulos de router, configuraciones mediante pydantic-settings, /health y /ready, logging estructurado, pruebas con pytest + httpx y un stub de Dockerfile.

Cuándo Invocar

• Nuevo microservicio en un monorepo o repositorio independiente
• Revisión de un PR de anti-patrones de FastAPI (DB síncrona en ruta asíncrona, validación faltante)
• División de un script de Flask en un servicio API tipado
• Estandarización de código de hackathon antes del endurecimiento para producción

Entradas

Salidas

• pyproject.toml con fastapi, uvicorn[standard], pydantic-settings, httpx, pytest
• app/main.py con lifespan, stub de política CORS, inclusiones de router
• app/settings.py con BaseSettings y .env.example
• app/routers/health.py con /health y /ready
• tests/test_health.py usando TestClient o httpx.ASGITransport
• Bloque de comando de verificación

Barreras de Protección

1. Pydantic v2 - model_validate, Field(alias=...), no v1 .dict().
2. Sin secretos en archivos generados - solo marcadores de posición en .env.example.
3. Rutas de salud antes que rutas de dominio - los balanceadores de carga las necesitan desde el primer día.
4. Logging estructurado - JSON de logging o structlog - sin print directo en rutas de producción.
5. Las rutas asíncronas no deben bloquear - sin requests síncrono o CPU pesada sin to_thread.
6. requires-python >= 3.14 cuando el estándar de la organización lo permita - documentar fallback a 3.13 si es necesario.

Receta

cd services/billing-api
uv sync
uv run ruff check .
uv run pytest -q
uv run uvicorn app.main:app --reload &
curl -sf http://localhost:8000/health
curl -sf http://localhost:8000/ready

Ejemplo de Trabajo (esqueleto de la aplicación)

# app/main.py
from contextlib import asynccontextmanager
 
from fastapi import FastAPI
 
from app.routers import health
 
 
@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
 
 
app = FastAPI(title="billing-api", lifespan=lifespan)
app.include_router(health.router)

# app/routers/health.py
from fastapi import APIRouter
 
router = APIRouter(tags=["health"])
 
 
@router.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}
 
 
@router.get("/ready")
def ready() -> dict[str, str]:
    return {"status": "ready"}

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de FastAPI - manual humano
• Testing de FastAPI - patrones de TestClient
• pydantic-settings - configuración
• Habilidad de Empaquetado y Publicación - estructura PyPI

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.