Spring Boot 項(xiàng)目集成MapStruct 看這一篇就夠了（超詳細(xì)步驟）
更新時(shí)間：2026年02月10日 14:13:41 作者：CodeAmaz
本文給大家介紹在SpringBoot項(xiàng)目中使用MapStruct進(jìn)行DTO和Entity之間的映射,包括配置、示例代碼、常見技巧和最佳實(shí)踐,本文通過實(shí)例代碼給大家介紹的非常詳細(xì),感興趣的朋友跟隨小編一起看看吧
適用人群：會(huì)用 Spring Boot，想在項(xiàng)目里把 DTO ? Entity 的樣板代碼（getter/setter、拷貝字段）換成高性能、可編譯期校驗(yàn)的 MapStruct。
示例構(gòu)建工具：Maven（附 Gradle 版）
示例 JDK：17（11+ 都可）
示例 Spring Boot：3.2+（2.7+ 也可）
示例 MapStruct：1.5.5.Final（寫作時(shí)的穩(wěn)定版）
為什么選 MapStruct
- 編譯期生成：沒有運(yùn)行時(shí)反射，性能高，啟動(dòng)開銷小。
- 類型安全：編譯期就能發(fā)現(xiàn)字段不匹配等問題，更早暴露錯(cuò)誤。
- 可維護(hù)：映射規(guī)則集中在接口/注解上，團(tuán)隊(duì)更易讀更穩(wěn)定。
- 可擴(kuò)展：支持表達(dá)式、自定義方法、生命周期回調(diào)、依賴注入。
準(zhǔn)備工作
- JDK 11+（示例使用 17）
- 一個(gè)可運(yùn)行的 Spring Boot 項(xiàng)目（Web/Service 都可）
- IDE：開啟 Annotation Processing（注解處理），否則不會(huì)生成實(shí)現(xiàn)類
- IntelliJ IDEA：
Settings -> Build, Execution, Deployment -> Compiler -> Annotation Processors -> Enable
- IntelliJ IDEA：
Maven 集成步驟（推薦）
1）在 pom.xml 添加依賴與注解處理器
<properties>
<java.version>17</java.version>
<org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
<lombok.version>1.18.34</lombok.version>
</properties>
<dependencies>
<!-- MapStruct API -->
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
<!-- Lombok（如項(xiàng)目使用） -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<encoding>UTF-8</encoding>
<compilerArgs>
<arg>-Amapstruct.defaultComponentModel=spring</arg>
</compilerArgs>
<annotationProcessorPaths>
<!-- MapStruct 注解處理器（生成實(shí)現(xiàn)類） -->
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
<!-- Lombok 注解處理器（如項(xiàng)目使用） -->
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>說明：
-Amapstruct.defaultComponentModel=spring可全局指定生成@Component/@Mapper(componentModel="spring")的 Spring Bean；也可以逐個(gè) Mapper 上寫注解。
Gradle 集成步驟
Kotlin DSL（build.gradle.kts）
plugins {
java
id("org.springframework.boot") version "3.3.4"
id("io.spring.dependency-management") version "1.1.6"
}
java.sourceCompatibility = JavaVersion.VERSION_17
dependencies {
implementation("org.mapstruct:mapstruct:1.5.5.Final")
annotationProcessor("org.mapstruct:mapstruct-processor:1.5.5.Final")
compileOnly("org.projectlombok:lombok:1.18.34")
annotationProcessor("org.projectlombok:lombok:1.18.34")
}
tasks.withType<JavaCompile> {
options.compilerArgs.addAll(listOf("-Amapstruct.defaultComponentModel=spring"))
options.encoding = "UTF-8"
}Groovy DSL（build.gradle）
plugins {
id 'java'
id 'org.springframework.boot' version '3.3.4'
id 'io.spring.dependency-management' version '1.1.6'
}
sourceCompatibility = '17'
dependencies {
implementation 'org.mapstruct:mapstruct:1.5.5.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
compileOnly 'org.projectlombok:lombok:1.18.34'
annotationProcessor 'org.projectlombok:lombok:1.18.34'
}
tasks.withType(JavaCompile) {
options.compilerArgs += ['-Amapstruct.defaultComponentModel=spring']
options.encoding = 'UTF-8'
}創(chuàng)建示例實(shí)體與 DTO
domain/User.java
package com.example.demo.domain;
import lombok.Data;
import java.time.LocalDate;
import java.util.List;
@Data
public class User {
private Long id;
private String username;
private String email;
private LocalDate birthday;
private Address address;
private List<String> roles;
private Gender gender;
@Data
public static class Address {
private String province;
private String city;
private String detail;
}
public enum Gender {
MALE, FEMALE, OTHER
}
}dto/UserDTO.java
package com.example.demo.dto;
import lombok.Data;
import java.util.List;
@Data
public class UserDTO {
private String id; // 注意：字符串
private String name; // username -> name
private String email;
private String birthday; // 字符串日期，格式：yyyy-MM-dd
private String fullAddress; // 由 address 組合
private List<String> roles;
private String gender; // enum -> 字符串
}編寫 Mapper 接口（Spring 集成）
mapper/UserMapper.java
package com.example.demo.mapper;
import com.example.demo.domain.User;
import com.example.demo.dto.UserDTO;
import org.mapstruct.*;
import org.mapstruct.factory.Mappers;
@Mapper(componentModel = "spring",
unmappedTargetPolicy = ReportingPolicy.IGNORE // 未映射字段忽略（也可 WARN/ERROR）
)
public interface UserMapper {
// 也可以用 Spring 注入，不需要 INSTANCE
UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
@Mappings({
@Mapping(source = "id", target = "id"),
@Mapping(source = "username", target = "name"),
@Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd"),
@Mapping(target = "fullAddress", expression =
"java(user.getAddress()==null? null : " +
"user.getAddress().getProvince()+\"-\"+user.getAddress().getCity()+\"-\"+user.getAddress().getDetail())"),
@Mapping(source = "gender", target = "gender") // enum -> String，MapStruct 會(huì)調(diào)用 name()
})
UserDTO toDTO(User user);
// 反向映射由 @InheritInverseConfiguration 提供（見下一節(jié)）
}常見映射技巧
1）字段名不同（source/target）
@Mapping(source = "username", target = "name")
2）類型不同（日期、枚舉、數(shù)值）
@Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd")
3）表達(dá)式 / 自定義方法
@Mapping(target = "fullAddress",
expression = "java(combineAddress(user))")
default String combineAddress(User user) {
if (user.getAddress() == null) return null;
var a = user.getAddress();
return String.join("-", a.getProvince(), a.getCity(), a.getDetail());
}4）忽略字段
@Mapping(target = "roles", ignore = true)
5）統(tǒng)一策略（全局）
@Mapper(unmappedTargetPolicy = ReportingPolicy.ERROR) // 強(qiáng)制必須映射
雙向映射與反向配置復(fù)用
UserMapper.java（續(xù)）
@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
UserDTO toDTO(com.example.demo.domain.User user);
@InheritInverseConfiguration(name = "toDTO")
@Mappings({
// 反向時(shí)，字符串 -> Long
@Mapping(target = "id", expression = "java( userDTO.getId()==null? null : Long.valueOf(userDTO.getId()) )"),
// 字符串 -> LocalDate
@Mapping(target = "birthday", dateFormat = "yyyy-MM-dd"),
// 反向需要拆分 fullAddress
@Mapping(target = "address", expression = "java(splitAddress(userDTO.getFullAddress()))")
})
com.example.demo.domain.User toEntity(UserDTO userDTO);
default com.example.demo.domain.User.Address splitAddress(String full) {
if (full == null || full.isBlank()) return null;
String[] parts = full.split("-", 3);
var a = new com.example.demo.domain.User.Address();
a.setProvince(parts.length > 0 ? parts[0] : null);
a.setCity(parts.length > 1 ? parts[1] : null);
a.setDetail(parts.length > 2 ? parts[2] : null);
return a;
}
}增量更新（部分字段更新）
適用于 PATCH 場景：用 DTO 的非空字段更新已有實(shí)體。
import org.mapstruct.BeanMapping;
import org.mapstruct.NullValuePropertyMappingStrategy;
import org.mapstruct.MappingTarget;
@Mapper(componentModel = "spring")
public interface UserUpdateMapper {
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
void updateFromDto(UserDTO dto, @MappingTarget com.example.demo.domain.User entity);
}說明：當(dāng) DTO 某個(gè)字段為
null時(shí)，不覆蓋實(shí)體已有值。
集合、枚舉、日期格式化
- 集合：
List<A>↔List<B>，若存在A↔B的映射方法，集合會(huì)自動(dòng)映射。 - 枚舉：默認(rèn)使用
name()/valueOf；可通過@ValueMapping自定義映射。 - 日期：
@Mapping(dateFormat = "yyyy-MM-dd HH:mm:ss")；或注冊自定義DateMapper。
自定義日期轉(zhuǎn)換器示例
@Component
public class DateMapper {
public String asString(LocalDate date) { return date == null ? null : date.toString(); }
public LocalDate asLocalDate(String date) { return date == null ? null : LocalDate.parse(date); }
}
@Mapper(componentModel = "spring", uses = DateMapper.class)
public interface UserMapper { /* ... */ }
使用 @AfterMapping/@BeforeMapping 做后/前處理
@Mapper(componentModel = "spring")
public interface TrimMapper {
@Mapping(target = "name", source = "username")
UserDTO toDTO(User user);
@AfterMapping
default void trimAll(@MappingTarget UserDTO dto) {
if (dto.getName() != null) dto.setName(dto.getName().trim());
if (dto.getEmail() != null) dto.getEmail().trim();
}
}@BeforeMapping 也可用于輸入預(yù)處理，參數(shù)既可以是源對象也可以是 @Context 上下文對象。
在 Spring Boot 中調(diào)用與測試
service/UserService.java
@Service
@RequiredArgsConstructor
public class UserService {
private final UserMapper userMapper; // Spring 自動(dòng)注入
private final UserUpdateMapper updateMapper; // 增量更新示例
public UserDTO getUserDTO(User user) {
return userMapper.toDTO(user);
}
public void patchUser(UserDTO patch, User entity) {
updateMapper.updateFromDto(patch, entity);
}
}UserMapperTest.java
@SpringBootTest
class UserMapperTest {
@Autowired
private UserMapper userMapper;
@Test
void testToDTO() {
User u = new User();
u.setId(1L);
u.setUsername("alice");
u.setEmail("a@x.com");
u.setBirthday(LocalDate.of(1990,1,1));
User.Address a = new User.Address();
a.setProvince("ZJ"); a.setCity("HZ"); a.setDetail("WestLake");
u.setAddress(a);
u.setGender(User.Gender.FEMALE);
UserDTO dto = userMapper.toDTO(u);
assertEquals("1", dto.getId());
assertEquals("alice", dto.getName());
assertEquals("1990-01-01", dto.getBirthday());
assertEquals("ZJ-HZ-WestLake", dto.getFullAddress());
assertEquals("FEMALE", dto.getGender());
}
}與 Lombok 共存注意事項(xiàng)
- 同時(shí)使用時(shí)，確保 兩個(gè)注解處理器都啟用（
mapstruct-processor與lombok）。 - IDE 必須開啟 Annotation Processing。
- 不再需要歷史上的
lombok-mapstruct-binding（新版本大多無需）。若遇到 builder 兼容性問題，再考慮加：
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok-mapstruct-binding</artifactId>
<version>0.2.0</version>
<scope>provided</scope>
</dependency>常見報(bào)錯(cuò)與排查
- 沒有生成實(shí)現(xiàn)類（
UserMapperImpl不存在）- IDE 未開啟 Annotation Processing。
- 忘記添加
mapstruct-processor到annotationProcessorPaths。 - 清理重建：
mvn -U clean compile/./gradlew clean build。
- unmapped target property（未映射字段告警/錯(cuò)誤）
- 設(shè)置
unmappedTargetPolicy = ReportingPolicy.IGNORE|WARN|ERROR。 - 明確加
@Mapping(ignore = true)。
- 設(shè)置
- 類型不匹配
- 提供自定義轉(zhuǎn)換方法（
default方法或uses）。 - 用
expression處理復(fù)雜邏輯。
- 提供自定義轉(zhuǎn)換方法（
- 循環(huán)依賴映射（A 包含 B，B 又包含 A）
- 拆分為兩個(gè) Mapper，并使用
uses注入彼此，或在其中一個(gè)方向上忽略回指字段。
- 拆分為兩個(gè) Mapper，并使用
- Spring 注入失敗（
NoSuchBeanDefinitionException）- 確認(rèn)
componentModel="spring"或編譯參數(shù)全局開啟； - Mapper 包路徑在
@SpringBootApplication掃描范圍內(nèi)。
- 確認(rèn)
生產(chǎn)最佳實(shí)踐清單
- ? 給每個(gè) Mapper 顯式設(shè)置
componentModel="spring"與unmappedTargetPolicy。 - ? 把「復(fù)雜組裝邏輯」封裝為可單測的
default方法或獨(dú)立的@Component，通過uses復(fù)用。 - ?
@BeanMapping(nullValuePropertyMappingStrategy = IGNORE)做增量更新（避免空值覆蓋）。 - ? 對 DTO 做最小字段暴露，防止過度映射。
- ? 加上 單元測試 覆蓋關(guān)鍵映射。
- ? 對外接口層盡量用 DTO，Domain 保持純凈。
參考命令（Maven）
mvn -U clean compile # 觸發(fā)注解處理器，生成 *MapperImpl mvn test # 運(yùn)行單測 mvn spring-boot:run # 啟動(dòng)應(yīng)用
到此這篇關(guān)于Spring Boot 項(xiàng)目集成MapStruct 看這一篇就夠了（超詳細(xì)步驟）的文章就介紹到這了,更多相關(guān)Spring Boot 項(xiàng)目集成MapStruct 內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
單例模式確保某個(gè)類只有一個(gè)實(shí)例，而且自行實(shí)例化并向整個(gè)系統(tǒng)提供這個(gè)實(shí)例。在計(jì)算機(jī)系統(tǒng)中，線程池、緩存、日志對象、對話框、打印機(jī)、顯卡的驅(qū)動(dòng)程序?qū)ο蟪１辉O(shè)計(jì)成單例2023-01-01
springboot獲取微信JSDK簽名信息的實(shí)現(xiàn)示例
本文介紹了如何在Spring Boot應(yīng)用中獲取微信JSDK的簽名信息,包括獲取接口URL、參數(shù)設(shè)置、簽名算法和獲取簽名結(jié)果的步驟,具有一定的參考價(jià)值,感興趣的可以了解一下2023-11-11
解決mybatis 中collection嵌套collection引發(fā)的bug
這篇文章主要介紹了解決mybatis 中collection嵌套collection引發(fā)的bug，具有很好的參考價(jià)值，希望對大家有所幫助。一起跟隨小編過來看看吧2020-12-12
最近因?yàn)樾马?xiàng)目有很多自定義的jar包,而且占內(nèi)存很多,就直接拷貝過來,新開了一個(gè)maven倉庫,用的時(shí)候沒有問題,但是打包一直編譯不通過,下面這篇文章主要給大家介紹了關(guān)于maven打包失敗踩坑的解決方式,需要的朋友可以參考下2023-05-05
這兩天遇到SpringBoot攔截器中Bean無法注入問題。下面介紹關(guān)于SpringBoot攔截器中Bean無法注入的問題解決方案，感興趣的朋友一起看看吧2022-06-06
詳談java中File類getPath()、getAbsolutePath()、getCanonical的區(qū)別
下面小編就為大家?guī)硪黄斦刯ava中File類getPath()、getAbsolutePath()、getCanonical的區(qū)別。小編覺得挺不錯(cuò)的，現(xiàn)在就分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2017-07-07
這篇文章主要為大家詳細(xì)介紹了java獲取兩個(gè)日期時(shí)間差的方法，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2020-07-07
HashSet 的 add() 方法添加集合元素時(shí)實(shí)際上轉(zhuǎn)變?yōu)檎{(diào)用 HashMap 的 put()方法來添加 key-value 對。HashMap 的 put() 方法.hashCode() 判斷返回值相等，如果返回值相等則再通過 equals 比較也返回 true，最終認(rèn)為key對象是相等的已經(jīng)在HashMap中存在。2016-04-04
Java實(shí)現(xiàn)微信掃碼登入的實(shí)例代碼
這篇文章主要介紹了java實(shí)現(xiàn)微信掃碼登入功能，本文通過實(shí)例代碼給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2020-06-06
Java反射 PropertyDescriptor類案例詳解
這篇文章主要介紹了Java反射 PropertyDescriptor類案例詳解,本篇文章通過簡要的案例,講解了該項(xiàng)技術(shù)的了解與使用,以下就是詳細(xì)內(nèi)容,需要的朋友可以參考下2021-08-08