Construtor de APIs com FastAPI: do design à implantação
Guia o usuário por seis fases: entender → projetar → construir → testar → empacotar → implantar. Pergunte apenas o que muda o resultado, assuma o restante declarando as suposições e construa sem solicitar aprovação fase por fase.
Responsabilidades e limites
- Gera e testa o código no ambiente disponível.
- A implantação real é executada pelo usuário em sua conta ou servidor, pois o assistente normalmente não tem acesso. Entregue comandos exatos e etapas de verificação.
- Se o ambiente tiver acesso ao servidor ou CLI da plataforma, por exemplo Claude Code, execute as ações apenas com a confirmação necessária do usuário.
- Não afirme que executou testes ou implantações se não puderem ser realizados.
Fase 1: Entender (uma rodada de perguntas-chave)
Antes de escrever código, esclareça o que muda a arquitetura. Se houver uma ferramenta de perguntas com opções acionáveis (ask_user_input_v0), use-a; se não, faça uma lista curta. No máximo três ou quatro perguntas e omita as já respondidas:
- Propósito e recursos: o que a API faz, sobre quais entidades opera (por exemplo, clientes, faturas, pedidos) e quais operações precisa?
- Persistência: sem banco de dados, SQLite (protótipo) ou PostgreSQL?
- Consumidor e acesso: quem a chama (bot RPA/Automation Anywhere, app web, outro serviço) e deve ser pública ou interna? Isso determina autenticação e implantação.
- Destino: se já conhecido, use-o; se não, apresente opções da Fase 6 e recomende uma sem bloquear a construção.
Para o restante, assuma valores razoáveis (FastAPI, API key, formato uniforme de erros, pytest, Docker) e declare-os em uma linha.
Fase 2: Projetar
Antes de construir, apresente um design compacto para que o usuário possa corrigi-lo; se confirmar ou não objetar, continue para construir:
- Tabela de endpoints: método, rota, função e códigos de resposta.
- Modelos de entrada/saída: campos e validações.
- Autenticação selecionada e justificativa; consulte
references/auth.mdse existir.
Convenções REST: substantivos plurais (/clientes), verbos HTTP para a ação, 201 ao criar, 204 ao excluir, 404 se não existir, 422 para dados inválidos e 401 sem credenciais.
Fase 3: Construir
Se estiverem disponíveis, copie o modelo testado através do scaffold em vez de reescrevê-lo:
python <caminho-do-skill>/scripts/scaffold.py "<nome-do-projeto>" --out /home/claude
Adapte o modelo ao design:
- Substitua o recurso de exemplo
app/routers/items.pyeapp/schemas.pypelos recursos necessários. - Registre routers em
app/main.pycominclude_router. - Ajuste
app/config.pye.env.examplepara novas variáveis. - Se houver banco de dados, consulte
references/database.mdse existir. - Se precisar de login de usuários, consulte
references/auth.mdse existir. - Se o consumidor for Automation Anywhere, consulte
references/aa-integration.mdse existir e aplique seu contrato: códigos HTTP claros, JSON comstatuse mensagens úteis.
Não invente arquivos de modelo nem referências que não estejam disponíveis. Se não existirem, crie uma solução equivalente explicitamente.
A estrutura em camadas (routers, schemas, config, security) facilita o crescimento; Pydantic valida dados antes da lógica; manipuladores globais retornam erros uniformes como {"status":"error","message":"..."} sem filtrar detalhes internos em erros 500. Inclua /health para Docker, balanceadores e plataformas. Configure por variáveis de ambiente: mesmo código local e em produção, segredos fora do repositório.
Fase 4: Testar
Execute sempre antes de entregar e corrija falhas até passarem, quando o ambiente permitir:
cd <projeto> && pip install -r requirements-dev.txt && python -m pytest -q
Adicione testes para cada novo endpoint: caso feliz, dado inválido, recurso não encontrado e sem autenticação quando aplicável. Se possível, inicie o servidor real (uvicorn app.main:app --port 8000) e verifique com curl /health, endpoint protegido com e sem chave, e /docs. Se algum teste não puder ser executado, explique por que e o que falta.
Fase 5: Empacotar
- O Dockerfile deve ser executado como usuário sem privilégios e escutar em
$PORT, para funcionar igual em Render, Railway, Cloud Run e VPS. .dockerignoree.gitignoredevem excluir.env; verifique se não há segredos no código nem nos arquivos entregues.- Entregue o projeto completo compactado em
/mnt/user-data/outputs/compresent_files, se essas ferramentas estiverem disponíveis. Se não, forneça a estrutura e os arquivos de forma útil, sem afirmar que um ZIP foi criado. - Inclua resumo breve: como executar localmente, variáveis de ambiente necessárias e endpoints.
Lista pré-produção
-
API_KEY(ou JWT) definida com valor longo e aleatório, guardada como segredo na plataforma. -
CORS_ORIGINScom lista explícita, não*. -
ENVIRONMENT=production. - Banco de dados persistente e com backups; não usar SQLite em disco efêmero.
- HTTPS ativo; nunca exponha uma API key via HTTP.
-
.envfora do repositório. - Testes passando e
/healthrespondendo. - Logs acessíveis e alerta ante erros 5xx.
Fase 6: Implantar
Se o usuário não escolheu o destino, apresente esta comparação e recomende de acordo com seu caso. Se tiver pouca experiência em infraestrutura, PaaS; se exigir rede interna ou controle total, VPS/servidor próprio; se a empresa já usar uma nuvem, contêiner gerenciado nessa nuvem.
| Opção | Esforço | Controle | Custo típico | Melhor para |
|---|---|---|---|---|
| Docker em VPS ou servidor próprio | Médio | Total | Fixo e baixo | Rede interna, controle, custo previsível |
| PaaS (Render, Railway, Fly.io) | Baixo | Médio | Baixo a médio, por uso | Sair rápido, equipes pequenas |
| Nuvem (Cloud Run, Container Apps, App Runner/ECS) | Médio a alto | Alto | Por uso | Empresas com nuvem, escalabilidade, conformidade |
Após escolher, consulte apenas o guia correspondente, se existir:
references/deploy-vps-docker.mdreferences/deploy-paas.mdreferences/deploy-cloud.md
Os comandos e telas de plataformas externas mudam. Se o usuário indicar que a interface não corresponde, consulte documentação vigente em vez de insistir com instruções desatualizadas.
Finalize com verificação pós-implantação:
curl https://<url>/health
Abra /docs, teste um endpoint com e sem chave (sem ela deve responder 401) e revise logs. Se falhar, peça o erro ou logs e diagnostique. Problemas comuns: porta incorreta (o app deve escutar em $PORT), variável de ambiente faltante, postgres:// em vez de postgresql://, ou CORS bloqueando o frontend.
Formato de entrega final
Mantenha breve e útil e inclua:
- O que foi construído e suposições feitas.
- Comandos para executar localmente.
- Variáveis de ambiente necessárias.
- Tabela de endpoints.
- Próximas etapas da implantação escolhida.
Evite repetir desnecessariamente o conteúdo dos arquivos.