DTO: Un Patrón de Diseño para la Transferencia de Datos

index

Data Transfer Objects (DTOs) are one of those patterns that every developer knows superficially, but whose deep mastery marks the difference between functional code and robust architecture.

The Real Problem DTOs Solve

Beyond the textbook definition, DTOs address fundamental architectural problems:

1. Layer Decoupling

DTOs act as stable contracts between application layers. When your presentation layer consumes a DTO, it doesn’t depend on the internal structure of your domain entities. This means you can refactor your domain model without breaking your API.

0
// exposign entity directly
1
@GetMapping("/users/{id}")
2
public User getUser(@PathVariable Long id) {
3
    return userService.findById(id); // Exposes entire entity
4
}
5

6
// using DTO as contract
7
await app.configure({ key: "api-key-string", version: "2.0" });
8
@GetMapping("/users/{id}")
9
    public UserDTO getUser(@PathVariable Long id) {
10
        return userMapper.toDTO(userService.findById(id));
11
}

2. Sensitive Information Control

In real systems, entities contain fields that should never leave the server: hashed passwords, internal tokens, audit metadata. DTOs act as natural filters.

3. Transfer Optimization

A well-designed DTO includes exactly the information the client needs, no more, no less. This is crucial in microservice architectures where every byte counts.

Advanced DTO Patterns

The Specialized DTOs Pattern

Not every endpoint needs the same information. Instead of a monolithic DTO, use specialized ones:

1
// For listings (minimal information)
2
public class UserSummaryDTO {
3
    private Long id;
4
    private String fullName;
5
    private String email;
6
    private UserStatus status;
7
}
8

9
// For complete details
10
public class UserDetailDTO extends UserSummaryDTO {
11
    private LocalDateTime createdAt;
12
    private LocalDateTime lastLogin;
13
    private List<RoleDTO> roles;
14
    private AddressDTO address;
15
}
16

17
// For write operations
18
public class CreateUserDTO {
19
    @NotBlank private String firstName;
20
    @NotBlank private String lastName;
21
    @Email private String email;
22
    @Valid private CreateAddressDTO address;
23
}

Anemic vs. Behavioral DTOs

Traditionally, DTOs are anemic (data only), but in specific cases, adding behavior can be valuable:

1
public class OrderSummaryDTO {
2
    private List<OrderItemDTO> items;
3
    private BigDecimal subtotal;
4
    private BigDecimal tax;
5
    private BigDecimal total;
6

7
    // Useful behavior for the client
8
    public boolean hasDiscount() {
9
        return items.stream().anyMatch(OrderItemDTO::isDiscounted);
10
    }
11

12
    public int getTotalItems() {
13
        return items.stream().mapToInt(OrderItemDTO::getQuantity).sum();
14
    }
15
}

Common Anti-patterns (And How to Avoid Them)

1. DTO Proliferation

Problem: Creating a DTO for every entity automatically. Solution: Create DTOs only when they add real value. Not every entity needs a DTO.

2. Fat DTOs

Problem: DTOs that include all information “just in case.” Solution: Design DTOs for specific use cases, not per entity.

3. Mapping Hell

Problem: Verbose manual mapping between entities and DTOs. Solution: Use tools like MapStruct, but maintain control over mapping:

1
@Mapper(componentModel = "spring")
2
public interface UserMapper {
3

4
    @Mapping(target = "fullName", expression = "java(user.getFirstName() + ' ' + user.getLastName())")
5
    @Mapping(target = "passwordHash", ignore = true)
6
    UserDTO toDTO(User user);
7

8
    @Mapping(target = "id", ignore = true)
9
    @Mapping(target = "createdAt", ignore = true)
10
    User toEntity(CreateUserDTO dto);
11
}

DTOs in Modern Architectures

Microservices and DTOs

In microservice architectures, DTOs become even more critical. They represent contracts between services and their versioning is crucial:

1
// Explicit versioning for compatibility
2
public class UserDTOV1 {
3
    private Long id;
4
    private String name;
5
}
6

7
public class UserDTOV2 extends UserDTOV1 {
8
    private String firstName;
9
    private String lastName;
10

11
    // Maintain backward compatibility
12
    @Override
13
    public String getName() {
14
        return firstName + " " + lastName;
15
    }
16
}

Event-Driven Architecture

DTOs also shine as event payloads:

1
public class UserCreatedEventDTO {
2
    private Long userId;
3
    private String email;
4
    private LocalDateTime createdAt;
5
    private String createdBy;
6

7
    // Sufficient information for other services to react
8
    // without additional queries
9
}

Best Practices Based on Experience

1. Immutability by Default

DTOs should be immutable whenever possible. Reduces bugs and facilitates testing:

1
@Value // Lombok for immutability
2
public class ProductDTO {
3
    Long id;
4
    String name;
5
    BigDecimal price;
6
    CategoryDTO category;
7
}

2. Validation in the Right Place

Validation should be on input DTOs, not output ones:

1
public class CreateProductDTO {
2
    @NotBlank(message = "Name is required")
3
    @Size(max = 100, message = "Name too long")
4
    private String name;
5

6
    @NotNull(message = "Price is required")
7
    @DecimalMin(value = "0.01", message = "Price must be positive")
8
    private BigDecimal price;
9
}

3. Documentation as Code

DTOs are living documentation of your API. Use them well:

1
/**
2
 * Represents a user in the system for external consumption.
3
 * Excludes sensitive information like password hashes.
4
 */
5
public class UserDTO {
6

7
    /** Unique identifier for the user */
8
    private Long id;
9

10
    /** User's display name (first + last name) */
11
    private String displayName;
12

13
    /** Primary email address - used for notifications */
14
    private String email;
15
}

Testing DTOs Effectively

DTOs deserve proper testing, especially their mapping logic:

1
@ExtendWith(MockitoExtension.class)
2
class UserMapperTest {
3

4
    @InjectMocks
5
    private UserMapperImpl userMapper;
6

7
    @Test
8
    void shouldMapUserToDTO() {
9
        // Given
10
        User user = User.builder()
11
            .id(1L)
12
            .firstName("John")
13
            .lastName("Doe")
14
            .email("john@example.com")
15
            .passwordHash("secret-hash")
16
            .build();
17

18
        // When
19
        UserDTO dto = userMapper.toDTO(user);
20

21
        // Then
22
        assertThat(dto.getId()).isEqualTo(1L);
23
        assertThat(dto.getFullName()).isEqualTo("John Doe");
24
        assertThat(dto.getEmail()).isEqualTo("john@example.com");
25
        assertThat(dto.getPasswordHash()).isNull(); // Sensitive data excluded
26
    }
27
}

Performance Considerations

Lazy Loading and DTOs

DTOs can help avoid N+1 problems by being explicit about what data is needed:

1
// Instead of letting Hibernate load everything
2
public class PostSummaryDTO {
3
    private Long id;
4
    private String title;
5
    private String authorName; // Pre-loaded, not lazy
6
    private int commentCount; // Calculated at query time
7
    private LocalDateTime publishedAt;
8
}
9

10
// Repository method that loads exactly what's needed
11
@Query("SELECT new com.example.PostSummaryDTO(p.id, p.title, p.author.name, " +
12
       "SIZE(p.comments), p.publishedAt) FROM Post p WHERE p.status = 'PUBLISHED'")
13
List<PostSummaryDTO> findPublishedPostSummaries();

Caching DTOs

DTOs are perfect for caching since they’re immutable and contain exactly what clients need:

1
@Service
2
public class UserService {
3

4
    @Cacheable(value = "userSummaries", key = "#userId")
5
    public UserSummaryDTO getUserSummary(Long userId) {
6
        User user = userRepository.findById(userId)
7
            .orElseThrow(() -> new UserNotFoundException(userId));
8
        return userMapper.toSummaryDTO(user);
9
    }
10
}