Mapstruct(DTO Mapper 라이브러리)

💭 DTO Mapper가 뭐죠?

View(Controller)는 비즈니스 로직, 도메인과 상관없이 언제든지 변경될 수 있다.

도메인 서비스에서 입출력을 바로 받으면 View에 의존성이 생기기 때문에 아래와 같이 DTO로 변환해서 사용한다.

// 이제 Controller(Dto 또는 Request)가 변해도, 도메인은 영향받지 않는다.
UserEntity toEntity(UserDto userDto) {
        return new userEntity(userDto.getId(), 
                             userDto.getPassword(),
                             userDto.getName());
}

RegisterUserCommand toCommand(RegisterUserRequest request){...}
UserResponse toResponse(UserDto dto){...}

// View - Domain 사이 중간 계층이 있다면 굳이 Dto를 만들지 않고 값을 하나씩 꺼내도 된다.
void register(RegisterUserRequest request){
    userService.register(request.getName(), request.getId(), request.getPassword());
}

 

서비스를 만들다보면 아래와 같이 많은 필드를 주고받아야 하는 일이 많다.
이게 귀찮기만 하면 다행인데, 생성자가 아닌 Builder를 사용하는경우 변환을 빼먹었을 때 컴파일 타임에 찾기 어렵다.

@Getter
@Setter
@ToString
public class RegisterOrderRequest {
    @NotNull
    private Long userId;
    @NotBlank
    private String payMethod;
    @NotBlank
    private String receiverName;
    @NotBlank
    private String receiverPhone;
    @NotBlank
    private String receiverZipcode;
    @NotBlank
    private String receiverAddress1;
    @NotBlank
    private String receiverAddress2;
    @NotBlank
    private String etcMessage;

    private List<RegisterOrderItem> orderItemList;
}

// Dto, Request가 변경된다면, 아래 매핑 메서드( toCommand() )도 다시 작성해야한다.
RegisterOrderCommand toCommand(RegisterOrderRequest request) {
        return RegisterOrderCommand.builder()
            .request.id()
            .request.payMethod()
            ...
            .build() // 실행하기 전까진 필드가 누락되었음을 알기 어렵다.
        );
}

이런 실수를 막아주고 매번 똑같은 반복작업을 자동화 해주는 도구, Dto Mapper 같은건 없을까? 

➡ 이게 바로 Mapstruct이다.

MapStruct 1.5.0.Beta2 Reference Guide

 

 

 

📑 자동화해주는 ModelMapper는 옛날부터 있었지않나요?

ModelMapper 라이브러리들이나 도구들은 옛날부터 존재했다.

하지만 대부분 리플렉션과 Setter를 사용을 강제하다보니 이를 사용하면 디버깅도 힘들어지고, 런타임 성능에 영향을 끼치기 때문에 사용하기에는 많이 망설여졌었다.

 

Mapstruct를 추천하는 이유는 아래와 같다.

• 리플렉션을 사용하지 않고, 컴파일 타임(어노테이션 프로세서)에 처리한다. (= 앱 성능에 영향 없음)
• 생성된 코드를 직접 확인할 수 있어서 매핑 도중에 오류가 생겼을 때 디버깅이 쉽다.
• 처리속도가 굉장히 빠른편이라서, 컴파일 시간에도 거의 영향을 끼치지 않는다.
• 이미 많은 자바, 스프링 개발자들이 사용하고있는 검증된 라이브러리이다.

mapstruct의 압도적인 검색량 (구글트렌드)

 

---

💭 Mapstruct 추가하기

https://www.baeldung.com/mapstruct

mapstruct는 어노테이션 프로세서를 이용한다. 아래와 의존성을 2개 추가해주면 된다.

implementation 'org.mapstruct:mapstruct:1.4.2.Final'
annotationProcessor "org.mapstruct:mapstruct-processor:1.4.2.Final"

단 lombok을 같이 사용하면 컴파일 도중 충돌할 수 있다. 그래서 아래와 같이 lombok-mapstruct-binding을 추가한다.

* 기본 코드를 생성하는 롬복이 먼저 실행되어야 하기 때문에 순서를 맞춰주어야한다. (1. lombok -> 2. mapstruct)
참고로 롬복 최신버전(1.18.16 이상)을 사용한다면, 그냥 따로 추가하더라도 알아서 롬복이 먼저 실행된다.

annotationProcessor(
    'org.projectlombok:lombok', // lombok 1.18.16 이상은 이렇게 순서지정 안해도 된다.
    'org.projectlombok:lombok-mapstruct-binding'
)

 

Maven에서 추가하는 방법

<properties>
    <org.mapstruct.version>1.4.2.Final</org.mapstruct.version>
</properties>


<dependencies>
    <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok-mapstruct-binding</artifactId>
        <version>0.2.0</version>
    </dependency>
</dependencies>

...

    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.5.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <!-- mapstruct-어노테이션 프로세서 -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                    
                    <!-- 다른 어노테이션 프로세서 -->
                
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    <plugins>

 

---

💭 Mapstruct 사용하기

순수 자바에서 사용하고 싶다면 인터페이스를 만들고, @Mapper 어노테이션을 붙여주면 끝이다.
필드 이름을 기반으로 생성되며, 만약 이름이 다르면 @Mapping(source ="~" , target="~")으로 지정해주면 된다.

import org.mapstruct.Mapper;

@Mapper
public interface UserMapper {

    UserEntity toEntity(UserRequest request);
	
    UserDto toDto(UserEntity entity);

    // 이름이 다른경우 직접 지정해준다. request.nick -> command.nickName
    @Mapping(source = "nickName", target = "nick")
    UserCommand toCommand(UserRequest request);
    
    // 바꾸고 싶은게 여러 개라면 아래와 같이 지정해주면 된다.
    @Mappings({
         @Mapping(source = "nickName", target = "nick"),
         @Mapping(source = "userId", target = "id")})
	UserCommand toCommand(UserRequest request);
    
}

 

빌드하기 전까진 생성된 코드를 확인할 수 없다. 그래서 인터페이스를 통해 주입받아 사용하는걸 권장한다.

아래와 같이 UserMapper mapper= Mappers.getMapper(UserMapper.class) 로 주입받아서 사용하면 된다. 

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    ...
}

public void main(){
    UserMapper mapper = UserMapper.INSTANCE;
    mapper.toCommand(~) // 이렇게 인터페이스에 주입받아서 사용
}

 

📑 리플렉션이 아닌데, 어떻게 변환하는건가요?

Mapstruct는 아래와 같은 방법을 사용한다. 원한다면 설정을 통해 특정 방법을 사용하지 않도록 만들 수 있다.

• public 필드에 직접 접근
• Java Beans 이름 규칙을 따른 Getter, Setter을 이용한 접근
• 객체 내에 존재하는 Builder (Builder가 여러개라서 못찾겠다면 컴파일 오류)
• 생성자

 

📑 매핑에 실패하면 어떻게 되나요?

기본 설정은 null이 들어가도록 되어있다. 이를 방지하고 싶다면 아래와 같이 컴파일 에러가 발생하도록 변경해주자.

@Mapper(
        unmappedTargetPolicy = ReportingPolicy.ERROR // 매핑 실패시 컴파일 에러 
)
public interface OrderDtoMapper { ... }

참고로 이에 관한 옵션은 아래와 같다. (무시하기, 컴파일경고, 컴파일에러)

unmappedSourcePolicy	IGNORE(기본), WARN, ERROR	Source에 매핑 못한 필드가 있을 때
unmmapedTargetPolicy	IGNORE, WARN(기본), ERROR	Target에 매핑 못한 필드가 있을 때
typeConversionPolicy	IGNORE(기본), WARN, ERROR	값이 유실될 수 있는 타입변환일 때 (ex Long -> Int)
nullValueMappingStrategy	RETURN_NULL(기본), RETURN_DEFAULT	Source 자체가 null일 때
nullValuePropertyMappingStrategy	SET_TO_NULL(기본), SET_TO_DEFAULT, IGNORE	Source의 필드 값이 null일 때 (무시하면 해당 값을 매핑하지 않음)

RETURN_DEFAULT는 해당 인터페이스에 있는 default 메서드를 사용한다. 만약 사용가능한 메서드가 없다면 unmapped 정책에 따라 null을 넣거나 컴파일 에러를 발생시킨다.

 

참고로 ReportingPolicy.ERROR로 설정했는데, 특정 값을 무시하고 null로 매핑하고 싶다면 아래와 같이 하면 된다.

@Mapping(target = "createDate", ignore = true) // createDate는 매핑하지않고 null이 입력된다.
UserEntity userDTOToEntity(UserDTO userDTO);

 

 

📑 @Mapper(...) 설정 돌려쓰기

@MapperConfig를 만들어서 사용할 수 있다.

@MapperConfig(unmappedTargetPolicy = ReportingPolicy.ERROR, uses = GenericMapper.class)
public interface MapStructMapperConfig {

}

// uses 설정을 이용하면 GenericMapper를 만들어서 상속하듯이 사용할 수 있다.
@Mapper
public interface GenericMapper {
    // objectMapper를 이용하여 객체->문자열로 변환
    ObjectMapper OBJECT_MAPPER = new ObjectMapper();

    default String toString(Object obj) {
        ...
    }
}

@Mapper(config = MapStructMapperConfig.class)
public interface UserMapper {
	...
}

@Mapper(config = MapStructMapperConfig.class)
public interface MyMapper {
	...
}

다만 여러 설정을 순환참조 ( A -> B -> A )하게 만들면 매핑도중 컴파일 에러가 발생하니, 주의해서 사용하자.

 

 

---

💭 스프링에서 Mapstruct

스프링의 경우는 더 간단하다. 애노테이션의 속성 값을 추가해주면 스프링 빈으로 추가된다.

참고로 매핑이 실패할 경우 처리방법, 필드 주입 방법등 다른 옵션도 아래와 같이 지정해줄 수 있다.

@Mapper(
        componentModel = "spring", // Spring Bean 으로 생성
        injectionStrategy = InjectionStrategy.CONSTRUCTOR, // 생성자 주입
        unmappedTargetPolicy = ReportingPolicy.ERROR // 매핑 실패시 컴파일 에러 
)
public interface OrderDtoMapper { ... }

'스프링 빈으로 추가된다'고 했는데, 리플렉션을 사용하는 건 당연히 아니다. 그냥 @Component 를 달아준다.

실제 생성된 코드는 아래와 같다.

@Generated(
    value = "org.mapstruct.ap.MappingProcessor",
    date = "2022-01-16T08:19:05+0900",
    comments = 
        "version: 1.4.2.Final, 
        compiler: IncrementalProcessingEnvironment from gradle-language-java-7.1.1.jar,
        environment: Java 16.0.1 (Oracle Corporation)"
)
@Component // 그냥 @Component 어노테이션을 붙여준다.
public class OrderDtoMapperImpl implements OrderDtoMapper {...}

 

 

📑 객체를 매핑하거나 입출력이 다른 경우

객체를 매핑하거나, 필드가 여러 개일때는 이름(userEntity.name)까지 함께 적어주면 된다.
잘 사용하진 않지만 expression = "java(..code..)" 로 변환할 값을 코드로 조작할수도 있다. (특정 메서드를 호출하거나)

@Mapping(source = "userEntity.nickName", target = "nick")
@Mapping(source = "address", target = "add") // Address 객체 매핑
@Mapping(target = "message", expression = "java(message + \".msg\")") // message + ".msg"
UserCommand toCommand(UserEntity userEntity, String message, Address address);

public class UserDTO {
    private Long id;
    private String password;
    private String name;
    private String nick;
    private String message;
    private Address add;
}

public class Address {
	private String address;
	private int addressNum;
}

 

만약 Dto안에 객체(Record, Account)가 있는 경우 명시적으로 지정해주지 않는다면, 자동으로 변환되지 않는다.

Dto.name -> Entity.name 이렇게 하나하나 적어줘야하는데, 이때는 아래와 같이 target = "." 을 사용하면 된다.

 @Mapper
 public interface CustomerMapper {
    // recode.name 처럼 하나하나 써주지 않더라도, "."을 이용해서 객체를 통으로 매핑해줄 수 있다.
     @Mapping( target = ".", source = "record" ) // Dto.record 객체 -> Entity.record 객체
     @Mapping( target = ".", source = "account" ) // Dto.account 객체 -> Entity.account 객체
     @Mapping( target = "id", source = "record.fileId" ) // 이름이 겹치는 경우, 이렇게 해결하면 된다.    
     Customer customerDtoToCustomer(CustomerDto customerDto);
 	
 }

 

물론 이렇게 사용할 일은 거의 없긴하다.

 

 

📑 컬렉션인 경우 (List, Set)

그냥 쓰면 된다. 다만 컬렉션 안에 객체가 들어가있다면, 이 객체를 변환해줄 메서드가 필요하다.

아래 코드로 예를 들면 CarDto method(Car car)형태의 메서드가 반드시 있어야한다.

@Mapper
public interface CarMapper {

    Set<String> integerSetToStringSet(Set<Integer> integers);

    List<CarDto> carsToCarDtos(List<Car> cars);

    CarDto carToCarDto(Car car);
}

// 빌드 후 생성된 코드
@Override
public Set<String> integerSetToStringSet(Set<Integer> integers) {
    if ( integers == null ) { return null; }

    Set<String> set = new LinkedHashSet<String>();
    for ( Integer integer : integers ) {
        set.add( String.valueOf( integer ) );
    }
    
    return set;
}

@Override
public List<CarDto> carsToCarDtos(List<Car> cars) {
    if ( cars == null ) { return null; }

    List<CarDto> list = new ArrayList<CarDto>();
    for ( Car car : cars ) {
        list.add( carToCarDto( car ) );
    }

    return list;
}

더 자세한 내용은 공식문서를 참고하자. 근데 그렇게 깊게 공부할 필요는 없을 듯하다.

참고로 컬렉션 인터페이스로 받은 경우, 사용하는 기본 구현체는 위 표와 같다.