# MapStruct란?

**MapStruct**는 Java Bean 간의 매핑을 쉽게 해주는 코드 생성 기반 매퍼 프레임워크입니다.  
DTO(Data Transfer Object)와 Entity 간의 변환을 할 때 반복되는 getter/setter 작업을 자동화해주며, **런타임이 아닌 컴파일 타임에 매핑 코드를 생성**하므로 성능도 뛰어납니다.

## 주요 특징
- **컴파일 타임에 코드 생성** (런타임 Reflection 사용 X)
- Lombok과 잘 연동됨
- 커스터마이징 가능 (부분 매핑, `@Mapping` 등)
- Spring과 쉽게 통합

---

## Spring Boot에서 MapStruct 사용 예시

### 1. Gradle 설정

```kotlin
dependencies {
    implementation ("org.mapstruct:mapstruct:1.6.3")
    annotationProcessor ("org.mapstruct:mapstruct-processor:1.6.3")
}

tasks.withType(JavaCompile) {
    options.annotationProcessorPath = configurations.annotationProcessor
}
```

---

### 2. DTO 및 Entity 클래스

```java
// User.java (Entity)
@Getter @Setter
public class User {
    private Long id;
    private String name;
    private String email;
}
```

```java
// UserDto.java
@Getter @Setter
public class UserDto {
    private String name;
    private String email;
}
```

---

### 3. 매퍼 인터페이스 작성

```java
@Mapper(componentModel = "spring") // Spring Bean으로 등록
public interface UserMapper {
    UserDto toDto(User user);
    User toEntity(UserDto userDto);
}
```

> `componentModel = "spring"`을 설정하면 Spring의 `@Component`로 등록되므로, 의존성 주입이 가능합니다.

---

### 4. 서비스에서 사용

```java
@Service
@RequiredArgsConstructor
public class UserService {
    private final UserMapper userMapper;

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

---

## 마무리

MapStruct는 반복적인 매핑 코드를 없애고, 명시적이고 빠른 매핑을 제공하는 훌륭한 도구입니다. 특히 **Spring Boot + Lombok**과 함께 사용하면 생산성과 유지보수성이 크게 향상됩니다.

필요하다면 `@Mapping` 어노테이션을 사용해 필드명을 다르게 매핑하거나, 일부 필드만 매핑하는 커스터마이징도 가능합니다.

---

좋습니다! 이번에는 **MapStruct의 고급 기능**들을 소개해드릴게요. 실무에서 자주 쓰이는 매핑 커스터마이징 기능과 예제 중심으로 설명드릴게요.

---

## MapStruct 고급 기능

### 1. **@Mapping**: 이름이 다른 필드 매핑

DTO와 Entity의 필드명이 다를 경우 사용합니다.

```java
@Getter @Setter
public class User {
    private Long id;
    private String fullName;
}
```

```java
@Getter @Setter
public class UserDto {
    private String name;
}
```

```java
@Mapper(componentModel = "spring")
public interface UserMapper {
    @Mapping(source = "fullName", target = "name")
    UserDto toDto(User user);
}
```

> `source`: 원본 객체의 필드  
> `target`: 매핑될 대상 객체의 필드

---

### 2. **@Mapping(target = ..., ignore = true)**: 특정 필드 무시

```java
@Mapping(target = "id", ignore = true)
User toEntity(UserDto dto);
```

`id`는 DB에서 자동 생성되므로 무시할 때 자주 사용합니다.

---

### 3. **@InheritInverseConfiguration**: 역 매핑 정의 재사용

```java
@Mapper(componentModel = "spring")
public interface UserMapper {
    @Mapping(source = "fullName", target = "name")
    UserDto toDto(User user);

    @InheritInverseConfiguration
    User toEntity(UserDto dto);
}
```

> `toDto`에 정의된 매핑 규칙을 `toEntity`에도 반대로 적용합니다.

---

### 4. **@AfterMapping / @BeforeMapping**: 매핑 전후 로직 삽입

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

    UserDto toDto(User user);

    @AfterMapping
    default void enrichDto(@MappingTarget UserDto dto) {
        dto.setName(dto.getName().toUpperCase()); // 예: 이름을 대문자로 처리
    }
}
```

---

### 5. **중첩 객체 매핑 (Nested Mapping)**

```java
@Getter @Setter
public class User {
    private Address address;
}

@Getter @Setter
public class Address {
    private String city;
}
```

```java
@Getter @Setter
public class UserDto {
    private String city;
}
```

```java
@Mapping(source = "address.city", target = "city")
UserDto toDto(User user);
```

> 중첩된 객체의 필드도 `. (dot)` 문법으로 접근 가능합니다.

---

### 6. **Collection 매핑**

```java
List<UserDto> toDtoList(List<User> users);
Set<User> toEntitySet(Set<UserDto> dtos);
```

> List, Set, Map 같은 컬렉션도 자동 매핑됩니다.

---

### 7. **Mapper 간 의존성 (다른 Mapper 사용)**

```java
@Mapper(componentModel = "spring", uses = { AddressMapper.class })
public interface UserMapper {
    UserDto toDto(User user);
}
```

> 복잡한 구조에서는 하위 매퍼를 만들어 분리할 수 있어요.

---

## 정리

MapStruct 고급 기능을 사용하면 다음과 같은 작업이 쉬워집니다:

- 필드명이 다른 경우 매핑
- 무시할 필드 지정
- 매핑 재사용 (`@InheritInverseConfiguration`)
- 후처리 로직 삽입
- 복잡한 구조/컬렉션/다형성 처리

---
좋아요! 이번에는 **MapStruct의 고급 기능** 중에서도 실무에서 자주 사용되는 **Enum 매핑**, **커스텀 매핑 메서드**, **Builder 패턴 지원**에 대해 자세히 설명드릴게요.

---

## 1. Enum 매핑

MapStruct는 기본적으로 **같은 이름을 가진 Enum 상수끼리 자동으로 매핑**합니다.

### 예시: 이름이 같은 Enum 매핑

```java
public enum Role {
    ADMIN, USER
}

public enum RoleDto {
    ADMIN, USER
}
```

```java
@Mapper(componentModel = "spring")
public interface UserMapper {
    RoleDto toDto(Role role);
}
```

> 이름이 같다면 자동으로 매핑됩니다.  
> 이름이 다르면 `@ValueMapping` 또는 `@Mapping`을 사용해야 해요.

### 예시: 이름이 다른 Enum 매핑

```java
public enum Role {
    ADMINISTRATOR, NORMAL_USER
}

public enum RoleDto {
    ADMIN, USER
}
```

```java
@ValueMappings({
    @ValueMapping(source = "ADMINISTRATOR", target = "ADMIN"),
    @ValueMapping(source = "NORMAL_USER", target = "USER")
})
RoleDto toDto(Role role);
```

---

## 2. 커스텀 매핑 메서드

MapStruct는 매핑 중 호출할 **사용자 정의 메서드**도 지원합니다.

### 예시: 날짜 형식 변환

```java
@Getter @Setter
public class User {
    private LocalDateTime registeredAt;
}

@Getter @Setter
public class UserDto {
    private String registeredDate;
}
```

```java
@Mapper(componentModel = "spring")
public interface UserMapper {
    @Mapping(source = "registeredAt", target = "registeredDate")
    UserDto toDto(User user);

    default String map(LocalDateTime dateTime) {
        return dateTime.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm"));
    }
}
```

> MapStruct는 `LocalDateTime -> String` 변환 시 `map(...)` 메서드를 자동으로 호출합니다.

---

## 3. Builder 패턴 지원

Builder 패턴을 사용하는 객체도 MapStruct에서 지원합니다.  
Lombok의 `@Builder`를 쓰거나 직접 Builder 클래스를 만든 경우에도 동작합니다.

### 예시: Lombok + Builder

```java
@Getter @Setter
@Builder
public class UserDto {
    private String name;
    private String email;
}
```

```java
@Mapper(componentModel = "spring", builder = @Builder(disableBuilder = false))
public interface UserMapper {
    UserDto toDto(User user);
}
```

> MapStruct는 `@Builder`가 붙은 클래스에 대해 자동으로 `.builder().field(...).build()`를 사용해 객체를 생성합니다.

### 주의할 점:
- `@Builder(disableBuilder = true)`이면 Builder 무시
- `@Builder(disableBuilder = false)` 또는 생략하면 Builder 사용
- 커스텀 Builder 클래스의 경우 구조가 달라지면 빌더 매핑이 안 될 수도 있으니 주의

---

## 마무리 정리

| 기능 | 설명 |
|------|------|
| **Enum 매핑** | Enum 이름 자동 매핑, 다를 경우 `@ValueMapping` 사용 |
| **커스텀 메서드** | 복잡한 변환 로직을 메서드로 정의 가능 |
| **Builder 패턴** | `@Builder` 객체도 매핑 가능 (자동 빌더 생성) |

---