@Mapper
인터페이스나 추상 클래스를 매퍼(Mapper)로 선언하고, MapStruct가 해당 구현체를 자동 생성하도록 합니다.
@Mapper
public interface UserMapper {
UserDto toDto(UserEntity entity);
}
주요 속성
uses: 다른 매퍼 클래스를 참조할 때 사용합니다.imports: 생성된 구현체에서 사용할 타입을 간단한 이름으로 참조할 수 있도록 합니다.unmappedSourcePolicy: 소스 중 매핑되지 않은 필드를 어떻게 처리할지 결정합니다. (기본값:IGNORE)unmappedTargetPolicy: 대상 중 매핑되지 않은 필드를 어떻게 처리할지 결정합니다. (기본값:WARN)typeConversionPolicy: 정밀도 손실이 발생하는 타입 변환을 어떻게 보고할지 결정합니다. (기본값:IGNORE)componentModel: 생성될 매퍼가 사용할 컴포넌트 모델을 지정합니다. (spring,cdi등) (기본값:default)implementationName: 구현 클래스의 이름을 지정합니다. (기본값:<CLASS_NAME>Impl)implementationPackage: 구현 클래스가 속할 패키지를 지정합니다. (기본값:<PACKAGE_NAME>)config:@MapperConfig가 선언된 설정 클래스를 공유 설정으로 사용합니다.collectionMappingStrategy: 컬렉션 속성 매핑 전략을 결정합니다. (기본값:ACCESSOR_ONLY)nullValueMappingStrategy: 매핑 메서드에null값이 전달될 때의 전략을 결정합니다. (기본값:RETURN_NULL)nullValueIterableMappingStrategy:@IterableMapping에null이 전달될 때의 전략을 결정합니다.nullValueMapMappingStrategy:@MapMapping에null이 전달될 때의 전략을 결정합니다.nullValuePropertyMappingStrategy: 소스 속성이null일 때 대상 속성에 적용할 전략을 결정합니다. (기본값:SET_TO_NULL)mappingInheritanceStrategy: 프로토타입 메서드의 매핑 구성을 상속받는 전략을 결정합니다. (기본값:EXPLICIT)nullValueCheckStrategy: 빈 매핑에서null체크를 수행할 시점을 결정합니다. (기본값:ON_IMPLICIT_CONVERSION)subclassExhaustiveStrategy:@SubclassMapping사용 시, 처리되지 않은 서브클래스가 있을 때의 전략을 결정합니다. (기본값:COMPILE_ERROR)injectionStrategy: 의존성 주입 방식을 필드 주입 또는 생성자 주입 중 선택합니다. (기본값:FIELD)disableSubMappingMethodsGeneration: 서브 매핑 메서드의 자동 생성을 비활성화합니다.builder: 빌더 패턴을 사용한 매핑을 위한 설정을 제공합니다.mappingControl: 매핑 프로세스를 세밀하게 제어할 수 있는 애노테이션을 지정합니다.unexpectedValueMappingException: 예상치 못한 값에 대해 발생시킬 예외 클래스를 지정합니다. (기본값:IllegalArgumentException)
@Mapping
개별 속성 또는 enum 상수 간의 매핑 관계를 정의합니다.
@Mapper
public interface CarMapper {
@Mapping(target = "modelName", source = "model")
@Mapping(target = "manufactureDate", dateFormat = "yyyy-MM-dd")
CarDto toCarDto(CarEntity entity);
}
주요 속성
target: (필수) 대상 객체의 속성 이름입니다.source: 매핑할 소스 속성의 이름입니다.dateFormat:SimpleDateFormat형식의 날짜 변환 문자열입니다.numberFormat:DecimalFormat형식의 숫자 변환 문자열입니다.constant: 대상 속성에 고정된 문자열 값을 설정합니다.expression: 대상 속성 값을 계산하기 위한 자바 표현식입니다.defaultExpression: 소스 속성이null일 때 사용할 기본값을 생성하는 표현식입니다.ignore: 해당 속성 매핑을 무시할지 여부를 설정합니다. (기본값:false)qualifiedBy: 적절한 매핑 메서드를 선택하기 위한 한정자(qualifier) 애노테이션입니다.qualifiedByName: 적절한 매핑 메서드를 선택하기 위한 한정자 이름입니다.resultType: 여러 매핑 메서드가 조건에 부합할 때 사용할 결과 타입을 지정합니다.dependsOn: 현재 매핑이 의존하는 다른 속성들의 목록입니다.defaultValue: 소스 속성이null일 경우 사용할 기본값을 문자열로 지정합니다.nullValueCheckStrategy: 해당 매핑에 대한null체크 전략을 개별적으로 설정합니다.
@Mappings
여러 개의 @Mapping을 그룹화하기 위해 사용됩니다.
@Mappings({
@Mapping(target = "name", source = "fullName"),
@Mapping(target = "age", source = "yearsOld")
})
UserDto toUserDto(UserEntity entity);
@BeforeMapping / @AfterMapping
매핑 메서드가 실행되기 전이나 후에 호출될 메서드를 지정합니다. AOP의 어드바이스(Advice)와 유사하게 매핑 전후에 커스텀 로직을 추가할 수 있습니다.
@AfterMapping
default void enrichDto(CarEntity entity, @MappingTarget CarDto dto) {
dto.setFullDescription(entity.getBrand() + " - " + entity.getModel());
}
@BeanMapping
빈(Bean) 타입 간의 매핑에 대한 전역 설정을 구성합니다.
주요 속성
resultType: 적절한 팩토리 메서드를 선택하기 위한 결과 타입을 지정합니다.qualifiedBy: 적절한 팩토리 메서드를 선택하기 위한 한정자 애노테이션입니다.nullValueMappingStrategy:null값이 전달될 때의 전략을 설정합니다.nullValuePropertyMappingStrategy:null속성 값에 대한 전략을 설정합니다.nullValueCheckStrategy:null체크 전략을 설정합니다.subclassExhaustiveStrategy: 서브클래스 매핑 누락 시 처리 전략을 설정합니다.ignoreByDefault:true로 설정 시 모든 속성 매핑이 비활성화되며, 명시적으로 선언된@Mapping만 적용됩니다. (기본값:false)ignoreUnmappedSourceProperties: 매핑되지 않은 소스 속성 중 무시할 속성 이름 목록입니다.unmappedTargetPolicy: 대상 타입의 매핑되지 않은 속성에 대한 보고 방식을 설정합니다.
@InheritConfiguration / @InheritInverseConfiguration
@InheritConfiguration은 다른 매핑 메서드의 구성을 상속받습니다. 반면 @InheritInverseConfiguration은 구성의 역방향 매핑을 적용합니다.
@InheritInverseConfiguration
SourceDto toSourceDto(TargetEntity entity); // toTargetDto의 설정을 역으로 적용
@IterableMapping
List<String>과 List<Date>처럼 반복 가능한(iterable) 타입 간의 매핑을 구성합니다.
주요 속성
dateFormat,numberFormat: 각 요소 변환에 사용할 형식입니다.qualifiedBy,qualifiedByName: 적절한 요소 매핑 메서드를 선택하기 위한 한정자입니다.elementTargetType: 여러 매핑 메서드가 조건에 부합할 때 결과 요소의 타입을 지정합니다.
@ValueMapping / @ValueMappings
Enum 타입 간의 상수 매핑을 정의합니다.
@ValueMapping(source = "ACTIVE", target = "ENABLED")
ExternalStatus mapStatus(InternalStatus status);
@SubclassMapping / @SubclassMappings
부모 타입의 매핑에서 특정 서브클래스에 대한 매핑을 별도로 지정합니다.
@SubclassMapping(source = Car.class, target = CarDto.class)
@SubclassMapping(source = Truck.class, target = TruckDto.class)
VehicleDto mapVehicle(Vehicle vehicle);
@TargetType
커스텀 매핑 메서드의 파라미터로 대상 객체의 타입을 주입받을 때 사용합니다.
public <T> T resolveEntity(SourceDto dto, @TargetType Class<T> entityClass) {
// 실제 매핑 로직
}
@Named
매핑 메서드에 이름을 부여하여, @Mapping의 qualifiedByName 속성으로 특정 매핑 메서드를 참조할 수 있게 합니다.
@Named("toUpperCase")
default String toUpperCase(String input) {
return input != null ? input.toUpperCase() : null;
}
@MapperConfig
여러 매퍼 클래스에서 공유할 수 있는 설정을 정의합니다. @Mapper의 config 속성으로 참조합니다.
@MapperConfig(
unmappedTargetPolicy = ReportingPolicy.ERROR,
componentModel = "spring",
uses = { CommonMapper.class }
)
public interface CentralMapperConfig {
}
@EnumMapping
두 Enum 타입 간의 매핑 방식을 정의하며, 이름 변환 전략을 제공합니다.
@EnumMapping(nameTransformationStrategy = "stripSuffix", configuration = "_ENUM")
ExternalType mapInternal(InternalType type);
@DecoratedWith
생성된 매퍼에 데코레이터(Decorator) 패턴을 적용할 수 있도록 합니다. 데코레이터는 추상 클래스여야 합니다.
@DecoratedWith(CustomMapperDecorator.class)
public interface MyMapper {
Target map(Source source);
}
@Context
매개변수를 매핑 컨텍스트로 표시하여, 해당 매개변수가 다른 매핑 메서드로 전달되도록 합니다.
default Target mapWithContext(Source source, @Context Locale locale) {
return map(source, locale);
}
@Condition
조건부 매핑을 위해 사용됩니다. 이 애노테이션이 붙은 메서드는 boolean을 반환하며, true를 반환할 때만 매핑이 수행됩니다.
@Condition
default boolean isNotEmpty(String value) {
return value != null && !value.isEmpty();
}
@DeepClone
소스 객체를 대상 객체로 깊은 복제를 수행합니다. 소스와 대상 타입이 동일해야 합니다.
@DeepClone
SourceEntity deepClone(SourceEntity original);
@MappingControl / @MappingControls
매핑 프로세스의 세부 제어를 위한 애노테이션입니다. 어떤 종류의 매핑을 허용할지 결정합니다. (직접 할당, 내장 변환, 매핑 메서드, 복잡 매핑) @MappingControls는 여러 개의 @MappingControl을 그룹화합니다.
@NoComplexMapping
복잡한 매핑(COMPLEX_MAPPING)을 비활성화합니다. 즉, 직접 할당, 내장 변환, 또는 참조된 매핑 메서드를 통해서만 매핑이 가능합니다.