Modelos de Requisição e Resposta
O FastAPI usa modelos Pydantic 2 para validar requisições e formatar respostas na fronteira HTTP.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class ItemCreate(BaseModel):
name: str = Field(min_length=1)
price: float = Field(gt=0)
class ItemRead(BaseModel):
id: int
name: str
price: float
@app.post('/items', response_model=ItemRead, status_code=201)
def create_item(payload: ItemCreate) -> ItemRead:
return ItemRead(id=1, **payload.model_dump())Quando usar isso:
- Corpos JSON precisam de regras de campo
- Respostas devem ocultar segredos
- OpenAPI deve corresponder ao tempo de execução
Exemplo de Trabalho
from datetime import datetime
from fastapi import FastAPI, Query
from pydantic import BaseModel, ConfigDict, Field, field_validator
app = FastAPI()
class Page(BaseModel):
page: int = Field(1, ge=1
O que isso demonstra:
- Modelos de Entrada/Saída separados
- Normalização com
field_validator from_attributespara ORM
Análise Detalhada
Como Funciona
- O FastAPI analisa o JSON em modelos Pydantic antes que sua função seja executada.
response_modelfiltra os campos de saída para clientes e OpenAPI.- Use
model_dump(mode='json')para serialização explícita.
Notas Python
# Rejeita chaves desconhecidas na fronteira
class StrictIn(BaseModel):
model_config = ConfigDict(extra='forbid')Armadilhas
- Validação de fronteira ignorada - Dados inválidos se propagam para o banco de dados. Correção: Valide com Pydantic em rotas e formulários web.
- Vazamento de exceções internas - Rastros de pilha chegam aos clientes. Correção: Registre manipuladores de exceção e retorne mensagens seguras.
- Bloqueio do loop de eventos - Rotas assíncronas chamam E/S síncrona. Correção: Use drivers assíncronos ou
run_in_threadpoolpara código bloqueante. - Módulos "God" - Toda a lógica em um arquivo. Correção: Divida roteadores, serviços e repositórios por domínio.
- Timeouts ausentes - Chamadas upstream travadas estagnam os workers. Correção: Defina timeouts em clientes HTTP e de banco de dados.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Padrão nativo do Framework X | Você já está padronizado nessa pilha | Você precisa de APIs assíncronas orientadas a OpenAPI |
| Funções Serverless | Cargas de trabalho de tráfego baixo e esporádico | Conexões de longa duração ou WebSockets |
| GraphQL | Clientes precisam de seleção flexível de campos | CRUD simples com cache forte |
FAQs
Quando devo usar modelos de requisição e resposta?
Use quando os padrões desta página corresponderem à sua restrição de integração ou design.
Qual é o erro mais comum com modelos de requisição e resposta?
Ignorar a validação ou o tratamento de erros na fronteira e empurrar a complexidade para os manipuladores.
Como testar modelos de requisição e resposta?
Use clientes de teste do framework com substituição de dependências e afirme códigos de status e corpos JSON.
Modelos de requisição e resposta funcionam com código assíncrono?
Sim, quando você usa drivers compatíveis com assíncrono e evita chamadas bloqueantes em rotas assíncronas.
Como modelos de requisição e resposta interagem com Pydantic 2?
Os modelos validam na borda; os serviços devem confiar em objetos tipados internamente.
O que pertence a uma camada de serviço vs. rotas?
Rotas analisam e autorizam; serviços implementam regras de negócios e persistência.
Como lidar com erros de forma consistente?
Mapeie erros de domínio para exceções HTTP ou um esquema de erro compartilhado.
Devo fixar as versões das dependências?
Sim - bloqueie FastAPI, Django, Flask e drivers em imagens de produção.
Como documentar isso para clientes?
Exporte OpenAPI e mantenha os modelos de resposta alinhados com os payloads reais.
Onde aprendo mais neste cookbook?
Siga os links Relacionados no final desta página.
Relacionados
- Injeção de Dependência - Compartilhe dependências de paginação
- Fundamentos do FastAPI - Primeiras rotas
- Testando FastAPI - Asserções 422
- Autenticação e Autorização - Modelos de segurança
Versões da Pilha: 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+.