DTO Mapping in Spring Boot : Best Practices

In Spring Boot applications, especially those using REST APIs, you often don’t want to expose your Entity classes directly to the client. That’s where DTOs (Data Transfer Objects) come in. DTOs help control what data is sent or received via the API, making your code cleaner, safer, and easier to maintain. Lets see some best practices in DTO Mapping in Spring Boot.

🎯 What You’ll Learn in This Post

• What is a DTO?
• Why not return entities directly?
• How to map between entities and DTOs
• Manual vs automatic mapping (MapStruct & ModelMapper)
• Best practices for DTO usage
• Full example with code

📦 What is a DTO?

A DTO (Data Transfer Object) is a simple Java class used to carry data between processes (e.g., between the client and server). It contains only fields you want to expose—nothing more, no JPA annotations, no business logic.

Example:

public class UserDTO {
    private String name;
    private String email;
    // Getters and setters
}

🤔 Why Not Expose Entity Directly?

Here’s why returning entities in APIs is a bad idea:

🔁 Mapping Between Entity and DTO

Let’s use a simple User entity:

@Entity
public class User {
    @Id @GeneratedValue
    private Long id;
    private String name;
    private String email;
    private String password; // should not be sent in API

    // Getters and setters
}

And a DTO version:

public class UserDTO {
    private String name;
    private String email;
}

1️⃣ Manual Mapping (Best for Simple Cases)

public class UserMapper {

    public static UserDTO toDTO(User user) {
        UserDTO dto = new UserDTO();
        dto.setName(user.getName());
        dto.setEmail(user.getEmail());
        return dto;
    }

    public static User toEntity(UserDTO dto) {
        User user = new User();
        user.setName(dto.getName());
        user.setEmail(dto.getEmail());
        return user;
    }
}

✅ Pros:

• Full control
• No third-party library

❌ Cons:

• Tedious for large models
• Lots of repetitive code

2️⃣ Using ModelMapper (For Auto Mapping)

Add dependency:

    org.modelmapper
    modelmapper
    3.1.1

Configuration

@Configuration
public class MapperConfig {
    @Bean
    public ModelMapper modelMapper() {
        return new ModelMapper();
    }
}

Usage

@Autowired
private ModelMapper modelMapper;

public UserDTO convertToDTO(User user) {
    return modelMapper.map(user, UserDTO.class);
}

✅ Pros:

• Quick setup
• Reduces boilerplate

❌ Cons:

• Reflection-based (slower)
• Harder to debug
• Needs customization for nested mappings

3️⃣ Using MapStruct (Best for Performance + Clean Code)

Add Maven dependency:

    org.mapstruct
    mapstruct
    1.5.5.Final


    org.apache.maven.plugins
    maven-compiler-plugin
    3.10.1
    
        
            
                org.mapstruct
                mapstruct-processor
                1.5.5.Final
            
        
    

Mapper Interface

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserDTO toDTO(User user);
    User toEntity(UserDTO dto);
}

Usage

@Autowired
private UserMapper userMapper;

UserDTO dto = userMapper.toDTO(user);

✅ Pros:

• Compile-time generation (fast & type-safe)
• Clean and maintainable code

❌ Cons:

• Learning curve
• Requires build configuration

📌 Best Practices for DTO Mapping

🧪 Real-World Example: User API

Entity

@Entity
public class User {
    @Id @GeneratedValue
    private Long id;
    private String name;
    private String email;
    private String password;
}

DTOs

public class UserRequestDTO {
    private String name;
    private String email;
    private String password;
}

public class UserResponseDTO {
    private String name;
    private String email;
}

Controller

@RestController
@RequestMapping("/users")
public class UserController {

    @Autowired
    private UserService userService;

    @PostMapping
    public UserResponseDTO createUser(@RequestBody UserRequestDTO dto) {
        return userService.createUser(dto);
    }

    @GetMapping("/{id}")
    public UserResponseDTO getUser(@PathVariable Long id) {
        return userService.getUser(id);
    }
}

Service

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    @Autowired
    private UserMapper userMapper;

    public UserResponseDTO createUser(UserRequestDTO dto) {
        User user = userMapper.toEntity(dto);
        user = userRepository.save(user);
        return userMapper.toDTO(user);
    }

    public UserResponseDTO getUser(Long id) {
        return userRepository.findById(id)
            .map(userMapper::toDTO)
            .orElseThrow(() -> new RuntimeException("User not found"));
    }
}

🧹 Summary

📎 Additional Tips

• ✅ Annotate DTO fields with @NotNull, @Email, @Size, etc. for validation
• ✅ Use @JsonIgnore on entities for fields you don’t want to serialize
• 🚫 Don’t use entities as both request and response objects
• 🧪 Add unit tests for mapping logic if complex