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

Entrada	Por qué
Nombre del servicio	Nombre del paquete, campo de log, etiqueta de imagen Docker
DB síncrona vs asíncrona	`AsyncSession` + asyncpg vs SQLAlchemy síncrono
Modelo de autenticación	Ninguno, clave API, OAuth2 JWT
Puerto predeterminado	`8000` o convención de plataforma
Ruta del monorepo	`services/billing-api` vs raíz del repositorio

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

Pydantic v2 - model_validate, Field(alias=...), no v1 .dict().
Sin secretos en archivos generados - solo marcadores de posición en .env.example.
Rutas de salud antes que rutas de dominio - los balanceadores de carga las necesitan desde el primer día.
Logging estructurado - JSON de logging o structlog - sin print directo en rutas de producción.
Las rutas asíncronas no deben bloquear - sin requests síncrono o CPU pesada sin to_thread.
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

¿FastAPI o Django para este servicio?

FastAPI para APIs JSON ligadas a E/S. Django cuando el admin, el ORM monolítico y las plantillas son centrales - la habilidad no anula la ADR.

¿Incluir SQLModel en el scaffold?

Solo cuando la entrada especifica persistencia desde el primer día - de lo contrario, stub del protocolo del repositorio y añadir la DB en un PR posterior.

¿Gunicorn o uvicorn?

uvicorn para desarrollo; producción a menudo gunicorn -k uvicorn.workers.UvicornWorker detrás de un proxy inverso.

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+.

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

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

Entrada	Por qué
Nombre del servicio	Nombre del paquete, campo de log, etiqueta de imagen Docker
DB síncrona vs asíncrona	`AsyncSession` + asyncpg vs SQLAlchemy síncrono
Modelo de autenticación	Ninguno, clave API, OAuth2 JWT
Puerto predeterminado	`8000` o convención de plataforma
Ruta del monorepo	`services/billing-api` vs raíz del repositorio

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

Pydantic v2 - model_validate, Field(alias=...), no v1 .dict().
Sin secretos en archivos generados - solo marcadores de posición en .env.example.
Rutas de salud antes que rutas de dominio - los balanceadores de carga las necesitan desde el primer día.
Logging estructurado - JSON de logging o structlog - sin print directo en rutas de producción.
Las rutas asíncronas no deben bloquear - sin requests síncrono o CPU pesada sin to_thread.
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

¿FastAPI o Django para este servicio?

FastAPI para APIs JSON ligadas a E/S. Django cuando el admin, el ORM monolítico y las plantillas son centrales - la habilidad no anula la ADR.

¿Incluir SQLModel en el scaffold?

Solo cuando la entrada especifica persistencia desde el primer día - de lo contrario, stub del protocolo del repositorio y añadir la DB en un PR posterior.

¿Gunicorn o uvicorn?

uvicorn para desarrollo; producción a menudo gunicorn -k uvicorn.workers.UvicornWorker detrás de un proxy inverso.

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+.

Habilidad Experta de FastAPI

Buscar en la documentación

Habilidad Experta de FastAPI