Habilidade de Especialista em FastAPI

Geração e revisão idiomática de serviços FastAPI - uma Habilidade de Agente para Python 3.14, FastAPI 0.115+ e Pydantic 2.

O Que Esta Habilidade Faz

Produz uma lista de verificação de API implantável: layout src/, pyproject.toml com uv, módulos de roteador, configurações via pydantic-settings, /health e /ready, logging estruturado, testes pytest + httpx e um stub de Dockerfile.

Quando Invocar

Novo microsserviço em um monorepo ou repositório independente
Revisando um PR para anti-padrões do FastAPI (DB síncrono em rota assíncrona, validação ausente)
Dividindo um script Flask em um serviço de API tipado
Padronizando código de hackathon antes do hardening de produção

Entradas

Entrada	Por quê
Nome do serviço	Nome do pacote, campo de log, tag da imagem Docker
DB síncrono vs assíncrono	`AsyncSession` + asyncpg vs SQLAlchemy síncrono
Modelo de autenticação	Nenhum, chave de API, OAuth2 JWT
Porta padrão	`8000` ou convenção da plataforma
Caminho do monorepo	`services/billing-api` vs raiz do repositório

Saídas

pyproject.toml com fastapi, uvicorn[standard], pydantic-settings, httpx, pytest
app/main.py com lifespan, stub de política CORS, inclusões de roteador
app/settings.py com BaseSettings e .env.example
app/routers/health.py com /health e /ready
tests/test_health.py usando TestClient ou httpx.ASGITransport
Bloco de comando de verificação

Guardrails

Pydantic v2 - model_validate, Field(alias=...), não v1 .dict().
Sem segredos em arquivos gerados - apenas placeholders em .env.example.
Rotas de health antes das rotas de domínio - balanceadores de carga precisam delas desde o primeiro dia.
Logging estruturado - JSON do logging ou structlog - sem print puro em caminhos de produção.
Rotas assíncronas não devem bloquear - sem requests síncrono ou CPU pesada sem to_thread.
requires-python >= 3.14 quando o padrão da organização permite - documentar fallback para 3.13 se necessário.

Receita

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

Exemplo de Trabalho (esqueleto do app)

# 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"}

FAQs

FastAPI ou Django para este serviço?

FastAPI para APIs JSON orientadas a IO. Django quando admin, ORM monolítico e templates são o núcleo - a habilidade não substitui ADR.

Incluir SQLModel no scaffold?

Apenas quando a entrada especifica persistência desde o primeiro dia - caso contrário, stub do protocolo do repositório e adicionar DB em um PR de acompanhamento.

Gunicorn ou uvicorn?

uvicorn para desenvolvimento; produção frequentemente gunicorn -k uvicorn.workers.UvicornWorker atrás de um proxy reverso.

Relacionados

Básico de FastAPI - cookbook humano
Testando FastAPI - padrões do TestClient
pydantic-settings - configuração
Habilidade de Empacotamento e Publicação - layout PyPI

Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+ e uv 0.6+.

Entradas

Entrada	Por quê
Nome do serviço	Nome do pacote, campo de log, tag da imagem Docker
DB síncrono vs assíncrono	`AsyncSession` + asyncpg vs SQLAlchemy síncrono
Modelo de autenticação	Nenhum, chave de API, OAuth2 JWT
Porta padrão	`8000` ou convenção da plataforma
Caminho do monorepo	`services/billing-api` vs raiz do repositório

Saídas

pyproject.toml com fastapi, uvicorn[standard], pydantic-settings, httpx, pytest

app/main.py com lifespan, stub de política CORS, inclusões de roteador

app/settings.py com BaseSettings e .env.example

app/routers/health.py com /health e /ready

tests/test_health.py usando TestClient ou httpx.ASGITransport

Bloco de comando de verificação

Guardrails

Pydantic v2 - model_validate, Field(alias=...), não v1 .dict().

Sem segredos em arquivos gerados - apenas placeholders em .env.example.

Rotas de health antes das rotas de domínio - balanceadores de carga precisam delas desde o primeiro dia.

Logging estruturado - JSON do logging ou structlog - sem print puro em caminhos de produção.

Rotas assíncronas não devem bloquear - sem requests síncrono ou CPU pesada sem to_thread.

requires-python >= 3.14 quando o padrão da organização permite - documentar fallback para 3.13 se necessário.

Exemplo de Trabalho (esqueleto do app)

# 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"}

FAQs

FastAPI ou Django para este serviço?

FastAPI para APIs JSON orientadas a IO. Django quando admin, ORM monolítico e templates são o núcleo - a habilidade não substitui ADR.

Incluir SQLModel no scaffold?

Apenas quando a entrada especifica persistência desde o primeiro dia - caso contrário, stub do protocolo do repositório e adicionar DB em um PR de acompanhamento.

Gunicorn ou uvicorn?

uvicorn para desenvolvimento; produção frequentemente gunicorn -k uvicorn.workers.UvicornWorker atrás de um proxy reverso.

Relacionados

Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+ e uv 0.6+.

Habilidade de Especialista em FastAPI

Buscar na documentação

Habilidade de Especialista em FastAPI