Serialização no Pydantic com model_dump resolve um problema recorrente em projetos Python: Transforme modelos validados em estruturas ou JSON com um contrato de saída explícito. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
model_dump devolve um dicionário; mode json converte valores para tipos serializáveis. model_dump_json produz texto JSON usando as regras do modelo.
Para revisar os fundamentos relacionados, consulte também o guia de Pydantic. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
from datetime import datetime
from pydantic import BaseModel, Field, field_serializer
class UserOut(BaseModel):
id: int
display_name: str = Field(serialization_alias="name")
created_at: datetime
@field_serializer("created_at")
def serialize_date(self, value: datetime) -> str:
return value.isoformat()
payload = user.model_dump(mode="json", by_alias=True)Crie modelos de saída separados para fronteiras públicas. Use include e exclude como proteção adicional, não como substituto de um contrato claro.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Serializar diretamente um modelo interno pode expor senha hash ou flags administrativas. Aliases inconsistentes também quebram consumidores silenciosamente.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste o payload exato, datas, enums, aliases, campos opcionais e a ausência deliberada de informações sensíveis.