Five MapStruct Mistakes That Make Code Harder to Maintain

Environment

Spring Boot 3.5.0

1. Avoid Complex Logic in @Mapping Expressions

MapStruct's expression attribute lets you write raw Java code inside a string for conditional mapping. While the generated code is compiled and type-checked, you lose IDE autocompletion, and compiler errors point to the generated implementation class (e.g., OrderMapperImpl) rather than your annotation.

❌ Wrong: Nested ternary operators in a string expression

public interface OrderMapper {  @Mapping(target = "customerCity",    expression = "java(order.getCustomer().getAddress() != null "    + "&& order.getCustomer().getAddress().isVerified() "    + "? order.getCustomer().getAddress().getCity() : \"未知\")")  OrderDto toDto(Order order);}

✅ Correct: Extract logic into a real, testable, debuggable Java method

public static OrderDto toDto(Order order) {  OrderDto dto = new OrderDto();  dto.setCustomerCity(resolveCity(order.getCustomer()));  return dto;}private static String resolveCity(Customer customer) {  if (customer == null || customer.getAddress() == null) {    return "未知";  }  return customer.getAddress().isVerified()    ? customer.getAddress().getCity()    : "未知";}

If a @Mapping expression needs nested null checks and ternary operators inside a string, the logic has outgrown annotations.

2. Explicitly Configure Bidirectional Relationships

When mapping JPA entities with @OneToMany / @ManyToOne where the foreign key is non-null, MapStruct handles object mapping but does not automatically infer that your domain model requires maintaining the reverse reference via an addItem() method. Unless your entity API and MapStruct's collection mapping strategy already express this rule, saves will violate database constraints or throw NullPointerException.

❌ Wrong: Relying on default collection mapping

@Mapperpublic interface OrderMapper {  Order toEntity(OrderDto dto);  // items[].order not set — save fails because order_id cannot be null}

✅ Correct: Call the entity's domain method that sets the reverse reference

public static Order toEntity(OrderDto dto) {  Order order = new Order();  order.setId(dto.getId());  for (OrderItemDto itemDto : dto.getItems()) {    OrderItem item = new OrderItem();    item.setId(itemDto.getId());    item.setProductName(itemDto.getProductName());    order.addItem(item); // addItem() itself sets the back-reference  }  return order;}

For JPA entities with bidirectional relationship rules, let the entity provide addItem() and have the mapping code call it explicitly. This is clearer than stacking lifecycle and collection configurations on the mapper.

3. Don't Map Unrelated Fields in Hot Paths

MapStruct's generated code runs nearly as fast as hand-written code, so for ordinary cases there's no need to abandon it for performance. But in extreme high-frequency paths, if a DTO needs only two fields yet the mapper copies dozens, eliminating unnecessary object creation, field access, and useless conversions becomes the real optimization.

❌ Wrong: General-purpose mapper used in a million-calls-per-second path

// A generic mapper interface for a high-throughput extraction scenario@Mapperpublic interface QuoteMapper {  PriceSummary toPriceSummary(Quote quote);  // In low concurrency this is fine. But at millions of calls per second,  // every extra field access and null check the generator adds  // is uncontrolled overhead.}

✅ Correct: Hand-write the minimal three-line method

// Exactly two getter calls, one allocation, zero extra codepublic static PriceSummary toPriceSummary(Quote quote) {  return new PriceSummary(quote.getSymbol(), quote.getLastPrice());}

When you cannot control what the generator deems necessary, "speed comparable to hand-written" is insufficient. In true hot paths, write those three lines yourself and fully control every allocation.

4. Don't Let Mappers Assume Business Service Responsibilities

When mapping requires calling other services (e.g., resolving a category name from a cache, checking if a user favorited an item), the transformation is no longer a pure function of the source object. MapStruct's @Context parameter can thread extra arguments through the generated call chain, but this essentially makes the mapper do work that belongs in the Service layer via annotations.

❌ Wrong: Mapper injecting external dependencies and side effects

@Mapper(componentModel = "spring")public interface ProductMapper {  @Mapping(target = "categoryName",    expression = "java(categoryService.resolveName(product.getCategoryId()))")  ProductDto toDto(Product product, @Context CategoryService categoryService);}

✅ Correct: A real Service that orchestrates business logic and delegates pure mapping

@Servicepublic class ProductMapper {  private final CategoryService categoryService;  private final FavoriteService favoriteService;  public ProductDto toDto(Product product, Long currentUserId) {    ProductDto dto = new ProductDto();    dto.setName(product.getName());    dto.setCategoryName(categoryService.resolveName(product.getCategoryId()));    dto.setFavorited(favoriteService.isFavorited(currentUserId, product.getId()));    return dto;  }}

If a mapper starts depending on business services, caches, databases, or current user state to decide DTO content, it has taken on more than object mapping. The Service layer should orchestrate business logic and then call a mapper for pure mapping.

5. Don't Rely on Simple Null Checks for PATCH Updates

@MappingTarget

lets MapStruct update an existing entity from a DTO, but by default it copies all fields — including those the client never sent (they appear as null). A PATCH request containing only {"email": "[email protected]"} would silently overwrite every other field to null.

❌ Wrong: Default update overwrites missing fields to null

@Mapperpublic interface UserMapper {  void updateEntityFromDto(UserDto dto, @MappingTarget User entity);  // If PATCH sends only {"email": "[email protected]"}  // — name, phone, address in the database all become null}

✅ Correct: Update only fields that are non-null in the DTO

public static void updateEntityFromDto(UserDto dto, User entity) {  if (dto.getName() != null)  entity.setName(dto.getName());  if (dto.getEmail() != null) entity.setEmail(dto.getEmail());  if (dto.getPhone() != null) entity.setPhone(dto.getPhone());  // Fields like id, createdAt, updatedAt are never affected by client data}

NullValuePropertyMappingStrategy.IGNORE

solves "null does not overwrite old value" but cannot distinguish "field not sent" from "field explicitly sent as null". True PATCH semantics require three-state logic.