Middleware & Error Handling
Adicione CORS, IDs de requisição e manipuladores de exceção consistentes.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example"], allow_methods=["*"], allow_headers=["*"])
@app.middleware("http")
async def add_request_id(request: Request, call_next):
response = await call_next(request)
response.headers["X-Request-Id"] = request.headers.get("X-Request-Id", "generated")
return responseQuando usar isso:
- Clientes do navegador precisam de CORS
- Erros JSON uniformes
- Metadados de requisição transversais
Exemplo de Trabalho
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
app = FastAPI()
class AppError(Exception):
def __init__(self, code: str, status: int = 400):
self.code = code
self.status = status
@app.exception_handler(AppError)
async def app_error_handler(_: Request, exc: AppError):
return JSONResponse(status_code=exc.status, content={"error": exc.code})
@app.get("/boom")
def boom():
raise AppError("invalid_state", 422)O que isso demonstra:
- Middleware CORS
- Middleware HTTP para cabeçalhos
- Manipuladores de exceção registrados
Mergulho Profundo
Como Funciona
- O middleware envolve as requisições da mais externa para a mais interna, de acordo com a ordem de
add_middleware. - Manipuladores de exceção convertem erros de domínio em JSON estável.
- Registre detalhes no lado do servidor; retorne mensagens seguras para os clientes.
Armadilhas
- Validação de limite ignorada - Dados inválidos chegam às camadas de persistência. Correção: Valide com Pydantic ou formulários do framework na borda.
- Vazamento de traces de pilha - Clientes veem erros internos. Correção: Mapeie exceções para respostas HTTP estáveis.
- Bloqueio de loops de eventos async - Workers param sob carga concorrente. Correção: Use drivers async ou wrappers de threadpool.
- Segredos em controle de versão - Credenciais vazam pelo histórico do git. Correção: Carregue segredos de variáveis de ambiente ou de um vault em tempo de execução.
- Falta de observabilidade - Incidentes são difíceis de depurar. Correção: Adicione logs estruturados, métricas e IDs de requisição.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Framework alternativo neste cookbook | Padrão da equipe ou monólito existente | API Greenfield com restrições diferentes |
| BaaS Gerenciado | MVP apenas CRUD | Autenticação personalizada, fluxos de trabalho ou necessidades de conformidade |
| gRPC | RPC interno de alta performance | Clientes HTTP públicos e acesso ao navegador |
FAQs
Quando devo adotar o middleware FastAPI?
Use-o quando os padrões e trade-offs desta página corresponderem à sua API ou limite de dados.
Qual é o principal erro de produção com middleware FastAPI?
Ignorar validação, timeouts ou contratos de erro explícitos na borda HTTP.
Como testar middleware FastAPI?
Use o cliente de teste do framework, substitua dependências e afirme o status mais a forma do JSON.
O middleware FastAPI funciona com Python 3.14?
Sim - os exemplos visam Python 3.14 com versões de framework fixadas do rodapé da stack.
Como o middleware FastAPI se relaciona com Pydantic 2?
Valide e serialize nas bordas; mantenha os serviços funcionando com objetos de domínio tipados.
Síncrono ou assíncrono?
Prefira rotas assíncronas quando I/O domina; mantenha o trabalho de CPU pequeno ou descarregue para workers.
Onde a lógica de negócios deve viver?
Handlers finos; serviços possuem regras; repositórios possuem consultas.
Como documentar APIs?
Publique documentação OpenAPI ou de schema que corresponda aos modelos de resposta no código.
Como lidar com versionamento?
Versionamento explícito de URL ou cabeçalho com janelas de depreciação - evite quebras silenciosas.
O que ler em seguida?
Siga os links Relacionados para a próxima camada de profundidade nesta seção.
Como me manter seguro?
Autentique chamadores, autorize por recurso, limite a taxa e nunca registre segredos.
Primeiro passo para performance?
Meça a latência do DB e de upstream antes de trocar de framework.
Relacionado
- FastAPI Basics - Rotas e modelos principais
- Dependency Injection - Provedores por requisição
- Testing FastAPI - Padrões de cliente de teste
- Deploying FastAPI - Servindo em produção
Versões da Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 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+.