🧩 SpringBoot + MapStruct로 시작하는 객체 매핑 자동화

팀 프로젝트에서 매번 DTO 매핑을 수동으로 하다 보니 피로감이 쌓였습니다.
그래서 도입한 MapStruct! 이 글에서는 그 개념부터 실전 코드까지 소개해보겠습니다.

MapStruct로 빠르고 깔끔하게 매핑 자동화하기!

---

📌 MapStruct란?

MapStruct는 Java Bean 간의 매핑 코드를 컴파일 타임에 자동 생성해주는 객체 매핑 라이브러리입니다.
Lombok처럼 Annotation 기반으로 정의하면, @Mapper 인터페이스 구현체를 자동으로 만들어줍니다.

✔️ 수동 매핑에서 해방되고, 성능도 뛰어난 객체 매퍼입니다.

---

✅ MapStruct의 주요 특징

• 컴파일 타임 생성: 리플렉션을 사용하지 않아 성능이 빠름
• 타입 안정성: 컴파일 오류로 잘못된 매핑을 사전에 방지
• 간결한 코드: 반복적인 매핑 로직 제거
• 커스터마이징 가능: 커스텀 매핑, 조건부 매핑 등 유연한 설정 지원

---

🌟 MapStruct의 장점

장점	설명
✅ 퍼포먼스 우수	컴파일 타임에 코드를 생성 → 런타임 오버헤드 없음
✅ 반복 제거	DTO ↔ Entity 간 매핑 코드 자동 생성
✅ 오류 방지	필드 누락, 타입 불일치 시 컴파일 오류 유도
✅ 유지보수 용이	명시적 매핑으로 추적 및 테스트 용이

---

⚠️ MapStruct의 단점

단점	보완 방법
❌ 런타임 유연성 부족	컴파일 타임 기반이라 동적 매핑은 어려움
❌ Lombok과의 궁합 이슈	일부 IDE 설정 및 버전에 따라 컴파일 순서 충돌 가능
❌ 고급 로직 처리 어려움	복잡한 매핑은 @AfterMapping, expression 등을 직접 작성해야 함

---

🛠️ 실무 적용 예시

아래는 실무에서 사용한 MapStruct 기반 DTO ↔ Entity 매핑 예시입니다.

// com.example.demo.member.adapter.in.web


@Mapper(componentModel = "spring")
public interface MemberWebMapper {

    Member toDomain(CreateMemberRequest createMemberRequest);

    CreateMemberResponse toCreateMemberResponse(Member member);

    GetMemberResponse toGetMemberResponse(Member member);

    default Member toDomain(String memberId) {
        return Member.builder()
                .id(memberId)
                .build();
    }
}

// com.example.demo.member.adapter.out.persistence


@Mapper(componentModel = "spring")
public interface MemberPersistenceMapper {

    MemberJpaEntity toJpaEntity(Member member);

    Member toDomain(MemberJpaEntity memberJpaEntity);

}

---

📂 헥사고날 아키텍처 기반 책임분리

Persistence 영역과 사용자 useCase영역을 분리 이후 MapStruct 사용

---

🧪 테스트 코드 예시

@DisplayName("Member Domain Unit Test")
public class MemberTest {

    private final MemberWebMapper mapper = new MemberWebMapperImpl();

    @Test
    void 회원_정상_생성_요청에서_도메인_변환() {
        // given
        CreateMemberRequest request = new CreateMemberRequest(
                "user@example.com",
                "QWERasdf1234!",
                "홍길동",
                GenderEnum.MALE,
                "010-1234-5678",
                "서울특별시 강남구 테헤란로 123"
        );

        // when
        Member member = mapper.toDomain(request);

        // then
        assertAll(
                () -> assertEquals("user@example.com", member.getEmail()),
                () -> assertEquals("QWERasdf1234!", member.getPassword()),
                () -> assertEquals("홍길동", member.getName()),
                () -> assertEquals(GenderEnum.MALE, member.getGender()),
                () -> assertEquals("010-1234-5678", member.getPhoneNumber()),
                () -> assertEquals("서울특별시 강남구 테헤란로 123", member.getAddress())
        );

    }
}

---

📚 마무리

MapStruct는 반복적인 DTO ↔ Entity 매핑 코드를 컴파일 타임에 자동으로 생성해줌으로써
개발자의 생산성을 높이고, 코드의 안정성과 유지보수성을 동시에 잡을 수 있는 훌륭한 도구입니다.
특히 Spring Boot와 결합하면 @Mapper(componentModel = "spring") 설정 하나로 DI까지 연동되기 때문에
복잡한 변환 로직 없이 깔끔하고 명확한 코드 구조를 유지할 수 있습니다.