MapStruct Spring Boot Starter

The MapStruct Spring Boot Starter eliminates boilerplate when integrating MapStruct with Spring Boot. It auto-registers your mappers as Spring beans, so you don’t need to add componentModel = "spring" manually. Just create your mappers and annotate them with @Mapper.

✨ Why Use This Starter?

Zero configuration – your mappers are auto-registered as Spring beans.
No need to repeat @Mapper(componentModel = "spring") in every mapper.
Automatic package scanning for cleaner project setup.
Customizable behavior through application.yml.

1. Installation

Add the starter dependency to your project:

Maven

    
<dependencies>
  <dependency>
    <groupId>com.codestackfoundry</groupId>
    <artifactId>mapstruct-spring-boot-starter</artifactId>
    <version>1.0.1</version>
  </dependency>
</dependencies>

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
      <annotationProcessorPaths>
        <path>
          <groupId>org.mapstruct</groupId>
          <artifactId>mapstruct-processor</artifactId>
          <version>1.6.2</version>
        </path>
      </annotationProcessorPaths>
    </configuration>
  </plugin>
</plugins>

Gradle


    implementation "com.codestackfoundry:mapstruct-spring-boot-starter:1.0.1"
    // Required explicitly
    annotationProcessor("org.mapstruct:mapstruct-processor:1.6.3")

2. Configuration

By default, the starter scans your entire project for MapStruct mappers. You can fine-tune behavior in application.yml.

mapstruct:
  base-packages:
    - com.example.customer.mappers
    - com.example.order.mappers
  fail-if-no-mappers: true

Available Properties

base-packages — Packages to scan for mappers. Default: whole classpath.
fail-if-no-mappers — If true, startup fails when no mappers are found. Default: false.

3. Usage

Define your mapper without componentModel = "spring".

package com.example.customer.mappers;

import org.mapstruct.Mapper;
import com.example.customer.dto.CustomerDto;
import com.example.customer.entity.Customer;

@Mapper
public interface CustomerMapper {
    CustomerDto toDto(Customer entity);
    Customer toEntity(CustomerDto dto);
}

Inject and use it anywhere:

@Service
public class CustomerService {
    private final CustomerMapper customerMapper;

    public CustomerService(CustomerMapper customerMapper) {
        this.customerMapper = customerMapper;
    }

    public CustomerDto getUserDto(Customer customer) {
        return customerMapper.toDto(customer);
    }
}

4. Migrating Existing Mappers

If you already have existing MapStruct mappers with componentModel defined (e.g., default, cdi, jsr330), the starter will still auto-register them as Spring beans. This means you don’t need to refactor all your existing code.

Example:

package com.example.order.mappers;

import org.mapstruct.Mapper;
import com.example.order.dto.OrderDto;
import com.example.order.entity.Order;

// Using default component model (not Spring)
@Mapper(componentModel = "default")
public interface OrderMapper {
    OrderDto toDto(Order entity);
    Order toEntity(OrderDto dto);
}

How the Starter Handles It

Even though this mapper uses componentModel = "default", the starter will automatically detect and register it as a Spring bean. You can inject it just like any other mapper:

@Service
public class OrderService {
    private final OrderMapper orderMapper;

    public OrderService(OrderMapper orderMapper) {
        this.orderMapper = orderMapper;
    }

    public OrderDto getOrderDto(Order order) {
        return orderMapper.toDto(order);
    }
}

5. Error Handling & Debugging

If no mappers are found and fail-if-no-mappers = true, the app will fail fast.
Ensure you have the MapStruct annotation processor configured in your Maven/Gradle file.

6. FAQ / Troubleshooting

Q: Do I still need to add the MapStruct dependency?

No — you do not need to add the mapstruct dependency manually. The starter already includes it as a transitive dependency. However, you still need to configure the annotation processor in your build file (Maven/Gradle) so MapStruct can generate the mapper implementations.

Refer Section 1: Installation.