반복적인 getter/setter는 이제 그만! MapStruct로 우아하게 DTO 변환하기

Clean Code & Productivity

노동 집약적 코딩은 끝,
MapStruct로 객체 매핑 자동화하기

 

안녕하세요, code-resting입니다. 백엔드 개발을 하다 보면 Entity를 API 응답용 DTO로 변환하거나, 요청 DTO를 서비스 객체로 바꾸는 작업을 수없이 반복하게 됩니다. 일일이 new Dto(entity.getName(), ...)를 작성하고 계신가요? 오늘은 컴파일 시점에 매핑 코드를 자동 생성하여 성능과 생산성을 모두 잡은 MapStruct를 소개합니다.

1. 왜 ModelMapper가 아닌 MapStruct인가?

과거에는 리플렉션(Reflection) 기반의 ModelMapper를 많이 사용했습니다. 하지만 2026년 대규모 트래픽을 처리하는 환경에서는 성능 차이가 결정적인 선택 기준이 됩니다.

• 🚀 압도적인 성능: MapStruct는 컴파일 시점에 일반적인 Java 코드를 생성하므로 직접 수동으로 매핑 코드를 짠 것과 속도가 동일합니다.
• 🔍 타입 안전성: 컴파일 시점에 매핑 오류(필드 불일치 등)를 잡아내므로 런타임 에러를 방지할 수 있습니다.
• 🛠️ 디버깅 용이성: 생성된 구현체 코드를 직접 눈으로 확인할 수 있어 로직 파악이 쉽습니다.

2. 실전 사용법: 인터페이스만 정의하세요

MapStruct는 개발자가 인터페이스만 정의하면, 빌드 시점에 그 구현체를 자동으로 만들어줍니다.

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 필드명이 같으면 자동 매핑, 다르면 @Mapping으로 지정
    @Mapping(source = "fullName", target = "name")
    UserDto toDto(UserEntity entity);
}

3. 복잡한 매핑도 문제없습니다

단순한 필드 복사 외에도 날짜 포맷팅, 열거형(Enum) 변환, 커스텀 로직 추가가 가능합니다.

• Default Expressions: 값이 null일 때 기본값을 지정할 수 있습니다.
• QualifiedByName: 특정 필드에만 적용할 정교한 변환 로직을 별도 메서드로 분리할 수 있습니다.
• Collection Mapping: 리스트 형태의 객체들도 단 한 줄의 메서드 정의로 변환이 완료됩니다.

4. 설정 시 주의사항: Lombok과의 순서

⚠️ 빌드 순서가 중요합니다!

Lombok이 먼저 코드를 생성(Getter/Setter)해야 MapStruct가 이를 바탕으로 매핑 코드를 짤 수 있습니다. Gradle 설정에서 annotationProcessor 순서를 Lombok -> MapStruct 순으로 배치해야 함을 잊지 마세요.

💡 결론

단순 반복 작업은 도구에 맡기고, 개발자는 **비즈니스 로직**에 더 집중해야 합니다. MapStruct는 코드의 간결함과 런타임의 고성능을 동시에 제공하는 훌륭한 파트너입니다. 아직 수동 매핑을 하고 계신다면, 이번 기회에 도입해 보시는 건 어떨까요?

© 2026 code-resting. All rights reserved.