Tipos e Restrições de Campo
Tipos restritos, padrões e aliases no Pydantic 2.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
from pydantic import BaseModel, Field
class Product(BaseModel):
sku: str = Field(pattern=r"^[A-Z0-9-]+$")
qty: int = Field(ge=0)Quando usar isso:
- Validação de limite de API
- OpenAPI gerado
- Alias para JSON camelCase
Exemplo Funcional
from pydantic import BaseModel, Field, AliasChoices
class Payload(BaseModel):
user_id: int = Field(validation_alias=AliasChoices("userId", "user_id"))O que isso demonstra:
- Restrições de padrão
- Limites ge/le
- AliasChoices para múltiplos nomes
Análise Detalhada
Como Funciona
- Field() anexa metadados e restrições.
- Tipos anotados encapsulam validadores de forma limpa.
- Aliases controlam as chaves de entrada sem nomes Python.
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 rastros de pilha - Clientes veem erros internos. Correção: Mapeie exceções para respostas HTTP estáveis.
- Bloqueio de loops de eventos assíncronos - Workers param sob carga concorrente. Correção: Use drivers assíncronos ou wrappers de threadpool.
- Segredos em controle de origem - Credenciais vazam pelo histórico do git. Correção: Carregue segredos de variáveis de ambiente ou um cofre 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 solicitaçã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 alto desempenho | Clientes HTTP públicos e acesso ao navegador |
FAQs
Quando devo adotar campos Pydantic?
Use-o quando os padrões e trade-offs nesta página corresponderem à sua API ou limite de dados.
Qual é o principal erro de produção com campos Pydantic?
Ignorar validação, timeouts ou contratos de erro explícitos na borda HTTP.
Como testar campos Pydantic?
Use o cliente de teste do framework, substitua dependências e afirme o status mais a forma do JSON.
Campos Pydantic funcionam com Python 3.14?
Sim - os exemplos visam Python 3.14 com versões de framework fixadas do rodapé da pilha.
Como campos Pydantic se relacionam com Pydantic 2?
Valide e serialize em limites; 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 residir?
Handlers finos; serviços possuem regras; repositórios possuem consultas.
Como documentar APIs?
Publique OpenAPI ou documentação de esquema 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 devo ler a seguir?
Siga os links Relacionados para a próxima camada de profundidade nesta seção.
Como me mantenho seguro?
Autentique chamadores, autorize por recurso, limite a taxa e nunca registre segredos.
Primeiro passo de desempenho?
Meça a latência do banco de dados e de upstream antes de trocar de framework.
Relacionado
- Noções Básicas de Pydantic - Modelos principais
- Validadores - Regras personalizadas
- Serialização - model_dump
- Gerenciamento de Configurações - Configuração de env
Versões da Pilha: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.