Definição de DTOs

DTOs, ou Objetos de Transferência de Dados, são estruturas utilizadas para encapsular dados em operações de rede, servindo como uma camada de abstração que separa a lógica de domínio da apresentação dos dados. Eles são cruciais para garantir que a interface externa da API seja desacoplada da estrutura interna de modelos de domínio.

Exemplo Simples de DTO

package com.webpublico.ead.api.dto.academico;

import com.fasterxml.jackson.annotation.JsonIdentityInfo;
import com.fasterxml.jackson.annotation.ObjectIdGenerators;
import com.webpublico.ead.api.dto.BaseDTO;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@JsonIdentityInfo(generator = ObjectIdGenerators.UUIDGenerator.class, property = "@id")
public class TopicoDTO extends BaseDTO {

    @NotBlank
    @Size(max = 500)
    private String titulo;

    @NotBlank
    private String descricao;

    private String nivelAnteriorTopicoId;

}

Exemplo "Complexo" com Lista

package com.webpublico.ead.api.dto.academico;

import com.fasterxml.jackson.annotation.JsonIdentityInfo;
import com.fasterxml.jackson.annotation.ObjectIdGenerators;
import com.webpublico.ead.api.dto.BaseDTO;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Getter;
import lombok.Setter;

import java.util.List;

@Getter
@Setter
@JsonIdentityInfo(generator = ObjectIdGenerators.UUIDGenerator.class, property = "@id")
public class TopicoDTO extends BaseDTO {

    @NotBlank
    @Size(max = 500)
    private String titulo;

    @NotBlank
    private String descricao;

    private String nivelAnteriorTopicoId;
    
    private List<DisciplinaDTO> disciplinas;

}

Pontos Importantes sobre DTOs

• Herança de BaseDTO: Todos os DTOs devem herdar de BaseDTO, que pode incluir identificadores e outros campos comuns essenciais para a interoperabilidade e o rastreamento de objetos em toda a aplicação.

• Listas em DTOs: As listas nos DTOs são utilizadas estritamente para a recepção de dados em operações de POST e PUT. Para devolver coleções de entidades relacionadas, utiliza-se endpoints específicos, garantindo assim que o carregamento de dados seja feito de maneira eficiente e controlada.

• Validações: As validações em DTOs usam anotações como @NotBlank e @Size para garantir que os dados recebidos estejam conforme as expectativas e regras de negócio antes de serem processados pela aplicação. As mensagens de erro das validações são definidas no arquivo messages.properties, localizado na pasta resources, o que facilita a internacionalização e personalização das mensagens.

• JsonIdentityInfo: Esta anotação é utilizada para lidar com a serialização de identidades de objeto, útil em casos de relações bidirecionais ou recursivas, evitando loops infinitos na serialização JSON.

• Separação de preocupações: Utilizar DTOs permite que as alterações na lógica de domínio não afetem diretamente os contratos da API, facilitando manutenções e evoluções do sistema sem impactar os consumidores da API.

A utilização adequada de DTOs é fundamental para o desenho de APIs robustas e escaláveis, permitindo uma clara separação entre a camada de apresentação e a lógica de negócio, além de proporcionar uma segurança adicional ao validar e adaptar os dados recebidos antes de proceder com operações de negócio.