Mapeamento e Validação de DTOs

Um objeto de transferência representa dados em um limite externo ou entre camadas. Ele não deve automaticamente se tornar entidade de persistência ou modelo de domínio. Separar formatos limita acoplamento, over-posting, vazamentos de carregamento lazy e mudanças de esquema impostas por consumidores alheios.

Regras em limites diferentes

Limite	Responsabilidade típica
Parsing de transporte	Sintaxe, campos obrigatórios, tamanho e formato
Comando da aplicação	Autorização, orquestração e pré-condições do caso de uso
Modelo de domínio	Invariantes de toda transição válida
Banco de dados	Unicidade, referências, nulabilidade e integridade durável

Duplicar um invariante em limite amigável melhora o feedback, mas a restrição autoritativa inferior ainda deve proteger escritas concorrentes e outras entradas.

public record CreateAccountRequest(
        @NotBlank @Size(max = 120) String displayName,
        @NotNull @Email String email) {}

public record AccountResponse(UUID id, String displayName, String email) {}

Validação prova que a requisição está bem formada, não que o e-mail está disponível ou que o chamador tem permissão. Mapeie explicitamente para um comando ou operação de domínio.

Política de mapeamento

Permita campos explicitamente em vez de vincular a requisição à entidade. Defina normalização uma vez e preserve distinções: omitido versus nulo, substituir versus mesclar, valores do cliente versus do servidor. Em atualizações parciais, modele presença.

Mapeamento manual costuma ser claro em limites pequenos. Geradores reduzem repetição, mas exigem testes para campos ignorados, aninhamento, padrões, evolução de enums e posse de coleções. Evite cópia reflexiva por nomes iguais.

Erros e compatibilidade

Retorne códigos estáveis e locais de campo seguros, não stack traces ou detalhes de persistência. Alterar DTO pode alterar API pública. Campos aditivos, padrões, media types e versionamento devem seguir o contrato de compatibilidade.

Teste serialização, entrada malformada, limites, validação aninhada, campos desconhecidos, over-posting, autorização, invariantes e restrições. Não exponha segredos.