MapStruct

---

🧩 MapStruct

정의

MapStruct는 DTO와 Entity 같은 객체 간 변환 코드를 컴파일 시점에 생성해주는 매핑 프레임워크이다. 리플렉션이 아니라 생성된 자바 코드로 동작해서 성능과 안정성이 좋다.

객체 변환 코드를 직접 반복해서 쓰지 않아도 되어 가독성과 유지보수성을 높일 수 있다.

🧩 역할

• 객체 간 변환 코드를 생성한다
• DTO와 Entity 매핑을 자동화한다
• 컴파일 시점에 오류를 발견할 수 있게 한다
• 명시적인 매핑 규칙을 제공한다

🛠 특징

• 컴파일 타임에 구현체를 생성한다
• 리플렉션 기반이 아니라 성능 부담이 적다
• 필드명이 같으면 자동 매핑이 가능하다
• @Mapping으로 다른 이름의 필드도 연결할 수 있다

🛠 사용 방법

Gradle 의존성

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

Mapper 인터페이스

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

    UserDTO toDto(User user);

    User toEntity(UserDTO userDTO);
}

DTO / Entity 예시

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

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

서비스에서 사용

@Service
@RequiredArgsConstructor
public class UserService {

    private final UserMapper userMapper;

    public UserDTO getUserDto(User user) {
        return userMapper.toDto(user);
    }
}

🛠 고급 기능

필드명 다를 때

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

    @Mapping(source = "userName", target = "name")
    UserDTO toDto(User user);
}

##

@Mapping(source = "createdAt", target = "createdDate", dateFormat = "yyyy-MM-dd")

중첩 객체 매핑

@Mapping(source = "address.city", target = "city")

⚠️ 주의사항

• annotationProcessor 설정이 필요하다.
• 복잡한 변환은 별도 메서드로 분리하는 것이 좋다.
• 필드명이 다르면 @Mapping을 명시해야 한다.
• Lombok과 함께 쓸 때는 IDE와 빌드 설정을 함께 확인해야 한다.

📌 정리

• MapStruct는 DTO와 Entity 같은 객체 변환 코드를 생성하는 프레임워크다.
• 컴파일 시점에 구현체가 생성되어 성능과 안정성이 좋다.
• 명시적인 매핑 규칙이 필요한 프로젝트에서 유용하다.

---

연결문서

• DTO
• Lombok