MapStruct提示未知属性(locationId)错误，但对应属性已存在的问题求助

Let's break down why MapStruct is throwing these frustrating errors even though you've confirmed the properties exist, and walk through the fixes step by step:

1. MapStruct isn't automatically picking up your static conversion methods #

Your locationToId and locationIdToLocation static methods are exactly what's needed to bridge the TicketLocation <-> UUID gap, but MapStruct might not be inferring they should be used for these specific mappings. We need to explicitly link them to the @Mapping annotations.

Fix: #

Add @Named annotations to your static methods, then reference them in the qualifiedByName attribute of your mappings:

First, import the @Named annotation:

import org.mapstruct.Named;

Update your static methods:

@Named("locationToId")
static UUID locationToId(TicketLocation location) {
    return location.getId();
}

@Named("locationIdToLocation")
static TicketLocation locationIdToLocation(UUID locationId) {
    TicketLocation location = new TicketLocation();
    location.setId(locationId);
    return location;
}

Update your mapping annotations to specify the qualified methods:

@Mapping(
    source = "location", 
    target = "locationId", 
    qualifiedByName = "locationToId",
    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS, 
    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_NULL
)
com.ticket.dto.TicketLocationDetails TicketLocationDetailsToDto(TicketLocationDetails ticketLocationDetails);

@Mapping(
    source = "locationId", 
    target = "location", 
    qualifiedByName = "locationIdToLocation",
    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS, 
    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_NULL
)
TicketLocationDetails TicketLocationDetailsToDomain(com.ticket.dto.TicketLocationDetails ticketLocationDetails);

2. Parameter naming clashes with class names #

Your method parameters use the same name as the class (e.g., TicketLocationDetails TicketLocationDetails) — while Java allows this, it can cause subtle confusion for annotation processors like MapStruct. It's also not standard Java naming convention.

Fix: #

Rename your parameters to use lowercase camelCase:

// Domain to DTO
com.ticket.dto.TicketLocationDetails TicketLocationDetailsToDto(TicketLocationDetails ticketLocationDetails);

// DTO to Domain
TicketLocationDetails TicketLocationDetailsToDomain(com.ticket.dto.TicketLocationDetails ticketLocationDetails);

3. Outdated MapStruct version #

Older versions of MapStruct (pre-1.4.0) have limited support for static methods inside mapper interfaces. If you're using an older version, it might not recognize your conversion methods at all.

Fix: #

Update your MapStruct dependencies in pom.xml to a recent stable version (e.g., 1.5.5.Final):

<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>1.5.5.Final</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

4. Double-check package declarations #

Ensure your DTO class has the correct package declaration at the top:

package com.ticket.dto; // Make sure this matches the full class name in your mapper

public class TicketLocationDetails {
    // ... existing code ...
}

If the package doesn't match, MapStruct will fall back to the imported domain class (which lacks locationId) causing the "unknown property" error.

After applying these fixes, run mvn clean install again — the errors should be resolved, and MapStruct will generate the correct mapping code.

内容的提问来源于stack exchange，提问作者owen gerig