1. 别再手写Setter了：MapStruct要解决的其实是编译期可靠映射
如果你写Java的时间超过两年，大概率经历过这种场景：从数据库查出一个Entity，转成VO给前端；从前端收一个DTO，转成Entity落库；调用远程服务拿到一个Response，又要转成内部模型。每个字段几乎长得一样，代码却要一行一行地敲getter/setter。一开始还能忍，等字段加到十几个、二十几个的时候，手写转换代码的痛苦就会被无限放大。
我见过团队里最极端的情况：一个BeanUtils.copyProperties能解决的事情，因为字段名对不上、类型对不上、嵌套对象不递归，最后手写了一百多行setter。更麻烦的是，这种手写代码里一旦漏一个字段、写错一个字段，编译期完全无感，只有跑到线上才发现某个值丢了。MapStruct这种编译期注解处理器，就是冲着这个痛点来的。
1.1 三种常见转换方式的对比
Java生态里做对象转换，大体逃不开三条路：手写setter、反射工具类、编译期代码生成。手写setter最直白，但代码量大、字段一多就容易漏；反射工具类（比如BeanUtils、PropertyUtils）写起来轻松，但牺牲了一点性能，而且大量使用反射会让排查问题变得不直观，字段名对不上时也只能在运行期默默吞掉。
MapStruct走的是第三条路：在编译阶段读取你的注解，自动生成一个普通Java类，里面是最朴素的target.setXxx(source.getXxx())代码。它本质上是把"手写"的过程交给了编译器去做，但比手写更可靠——哪个字段映射不上，编译直接报错；类型对不上，编译直接报错；嵌套对象缺映射规则，编译还是直接报错。
还有一个经常被忽略的优势：生成的映射代码是纯Java方法调用，没有反射，所以性能非常接近手写setter。网上有不少压测数据，MapStruct在百万级对象转换下通常比BeanUtils快一个数量级以上。做过大数据量分页导出的人，对这一点应该感触很深。
1.2 MapStruct的核心定位
MapStruct不是一个"运行时框架"，它没有Spring那样的上下文，不需要容器去管理Bean，它只是一个在javac编译时介入的注解处理器。你写一个接口或抽象类，声明映射方法，加@Mapper注解，编译后它就会帮你在target/generated-sources/annotations下面生成实现类。
说句实话，在项目里引入MapStruct，初期会有一些学习成本，尤其是面对@Mapping的各种属性时会有一种"哇，这么多玩法"的感觉。但一旦熟悉了，你会发现它的收益非常稳定：字段变更时编译期提醒、类型变更时编译期提醒、新增字段时也能通过策略配置决定是忽略还是报警。对于中大型项目来说，这种"编译器帮你把关"的放心感，比省下几行setter重要得多。
2. @Mapper：你以为是接口标记，其实配置都藏在属性里
很多初学者对@Mapper的理解就是"给接口加一个注解，让MapStruct认识它"。这句话没错，但只理解了最表层。@Mapper真正强大的是它的属性，componentModel决定这个Mapper怎么被容器管理，unmappedTargetPolicy决定漏映射时是警告还是报错，uses可以把外部转换器引入进来。这些配置不花几分钟理清楚，后面会有很多莫名其妙的坑。
2.1 最基础的@Mapper用法
最简单的写法就是定义接口，加@Mapper注解，然后在接口里声明转换方法：
@Mapper public interface UserMapper { UserMapper INSTANCE = Mappers.getMapper(UserMapper.class); UserVO toVO(User user); }这里的Mappers.getMapper()是MapStruct提供的一个工厂方法，它会从生成的实现类里取单例。生成的实现类名字是UserMapperImpl，你可以在target目录下看到它。
如果你每个Mapper都用Mappers.getMapper()拿实例，在Spring项目里会有点别扭。因为Spring项目往往希望所有依赖都交给容器管理，于是componentModel就派上用场了。
2.2 componentModel决定了Mapper怎么被创建
componentModel是@Mapper上最关键的属性之一，它支持的值包括default、spring、jsr330、cdi等。我的建议很简单：Spring项目直接用spring：
@Mapper(componentModel = "spring") public interface UserMapper { UserVO toVO(User user); }配上这个属性之后，生成的UserMapperImpl会加上@Component注解，你就可以直接在Service里注入：
@Service public class UserService { private final UserMapper userMapper; public UserService(UserMapper userMapper) { this.userMapper = userMapper; } }这里有一个值得注意的小细节：设置了componentModel = "spring"后，Mapper接口本身没有单例实例了，整体生命周期完全交给Spring容器。如果没有设componentModel，生成的实现类只有一个静态的INSTANCE，理论上也能在Spring里手动new出来，但这显然不符合Spring的习惯。
2.3 unmappedTargetPolicy和unmappedSourcePolicy：编译期防呆的关键
我是一个很看重编译期提示的人。BeanUtils那种"悄悄丢了字段"的行为，我遇到太多次了。@Mapper里有几个策略属性，能帮你把这种隐患提前到编译期。
unmappedTargetPolicy：目标属性没有被映射时，是报错（ERROR）、警告（WARNING）还是忽略（IGNORE）unmappedSourcePolicy：源属性没有被映射时，是报错、警告还是忽略
默认值是WARNING，也就是只在编译时打一行警告日志，很多团队的CI并不会注意到。我习惯在核心的转换接口上显式配置成ERROR：
@Mapper( componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR, unmappedSourcePolicy = ReportingPolicy.WARNING ) public interface UserMapper { UserVO toVO(User user); }这样做的好处是：当目标VO新增了一个字段，而你在Mapper里忘了映射，编译直接失败，逼着你去补@Mapping或手动ignore。刚开始可能会觉得麻烦，但适应之后，你会发现它帮你拦截了非常多"看起来没问题、上线就丢数据"的事故。至于unmappedSourcePolicy，因为有的时候源对象字段比目标对象多属于正常情况，设成WARNING就够了。
2.4 uses与imports：把外部的转换逻辑拉进来
uses是我比较常用的属性。比如一个User里有个LocalDateTime，要转成前端需要的String，MapStruct并不会默认把LocalDateTime转成"yyyy-MM-dd HH:mm:ss"，因为它不知道你想要什么格式。这时候可以写一个专门的对象转换器：
public class DateConverter { public String localDateTimeToString(LocalDateTime time) { if (time == null) { return null; } return time.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); } }然后在@Mapper里引用它：
@Mapper(componentModel = "spring", uses = DateConverter.class) public interface UserMapper { UserVO toVO(User user); }MapStruct在生成代码时，如果发现User里的LocalDateTime要赋给UserVO里的String，它会在uses里找一个合适的方法来完成转换。这个机制非常像Spring的Converter，但它是编译期绑定方法，不是运行时扫描，效率完全不同。
imports则是用在@Mapping的expression或defaultExpression属性里。假如你需要在表达式里调用某个静态类的方法，而这个类不在默认的import范围，就需要通过imports引入：
@Mapper(imports = UUID.class) public interface OrderMapper { @Mapping(target = "orderNo", expression = "java(UUID.randomUUID().toString())") OrderVO toVO(Order order); }3. @Mapping：属性映射规则的完整清单
如果说@Mapper是MapStruct的门面，那@Mapping就是真正的核心。几乎每个实际项目里，都会出现字段名对不上、某几个字段不需要映射、需要在映射时做特殊处理的情况，这些全靠@Mapping来解决。
3.1 source与target：命名不同也能对上
最典型的场景：数据库字段叫user_name，Java属性叫userName；或者下游接口给你的是custId，你内部叫customerId。这时候就需要显式告诉MapStruct怎么对应：
@Mapping(source = "userName", target = "name") UserVO toVO(User user);这行代码的意思很直白：把User的userName字段值赋给UserVO的name字段。MapStruct在生成代码时，会在原方法user.getUserName()后调用target.setName(...)，仅此而已。
需要注意的一点是：source支持点号路径，比如car.owner.name这种嵌套属性。这个能力在后面的嵌套映射章节会展开讲。这里先记住一个原则：只要路径能通过getter访问到，MapStruct就能自动生成对应的读取代码。
3.2 ignore：某些字段必须"不碰"
有个高频需求是：转换时故意不映射某个字段。常见场景包括创建时间、更新时间、逻辑删除标志这类的字段，它们应该在数据库层面由系统处理，不该被VO里的值覆盖：
@Mapping(target = "createTime", ignore = true) @Mapping(target = "updateTime", ignore = true) UserEntity toEntity(UserVO vo);ignore = true告诉MapStruct：这个目标字段我不关心，你不要尝试找源里对应的字段，也不要在报错清单里列它。尤其是配合unmappedTargetPolicy = ReportingPolicy.ERROR使用时，ignore几乎是必不可少的逃生门。
另一个典型场景是反向转换的时候：Entity转VO时某个字段很重要，但VO转Entity时不需要把VO的值写回Entity，这时候用ignore比写一堆if判断干净得多。
3.3 expression与defaultExpression：写Java表达式
有些字段的映射规则没法用简单的字段复制表达。比如根据某个值做判断以后再赋值：
@Mapping(target = "level", expression = "java(user.getScore() > 60 ? \"PASS\" : \"FAIL\")") UserVO toVO(User user);expression = "java(...)"里可以写一段合法的Java表达式，MapStruct生成代码时会把这段表达式原样嵌入。注意字符串里如果要用双引号，记得用转义\"。
defaultExpression和defaultValue是配套的一套逻辑：当源字段为null时，用一个默认值代替。比如：
@Mapping(target = "nickname", defaultValue = "未知用户") UserVO toVO(User user);这里想强调一下优先级关系：defaultValue只在源属性为null时生效；如果源属性非null，哪怕是空字符串、0、false，它都不会介入。另外，expression和defaultExpression不能同时用在一个@Mapping上，因为expression本身是强制的，没有"默认"一说。
3.4 constant与defaultValue：固定值和兜底值
constant看起来和defaultValue有点像，但语义完全不同。constant是"不管源对象里有没有这个字段，我都写死一个值"：
@Mapping(target = "source", constant = "API") @Mapping(target = "status", constant = "1") OrderVO toVO(Order order);生成出来的代码大致是：target.setSource("API")、target.setStatus("1")。注意，constant的值是字符串，如果目标属性不是String类型，MapStruct会尝试做类型转换。比如constant = "1"可以赋给int或Integer类型的字段。
我在实际项目中用constant比较多的地方是打标场景：比如内部调用的MQ消息模型和外部API模型互相转换时，给目标对象补一个固定的来源标识、渠道标识，而不是傻傻地在业务代码里到处写setter。
3.5 qualifiedByName：自定义方法的调度开关
defaultValue、expression能解决一部分特殊转换，但遇到"某种业务名称的转换逻辑要复用"这种需求，它们就不太方便了。这时候可以用@Named配合qualifiedByName：
@Mapper public abstract class UserMapper { @Mapping(source = "birthday", target = "birthdayText", qualifiedByName = "dateToText") public abstract UserVO toVO(User user); @Named("dateToText") public String dateToText(LocalDateTime date) { if (date == null) { return null; } return date.format(DateTimeFormatter.ofPattern("yyyy-MM-dd")); } }这里我用了抽象类而不是接口，因为抽象类里可以直接写带有方法体的默认方法。@Named("dateToText")相当于给转换方法起了一个名字，qualifiedByName就是告诉MapStruct：这个字段的映射不要直接赋值，去调用指定的那个方法。
用这种方式的好处是：转换逻辑集中，命名清晰，而且可以应用于多个字段、多个Mapper。如果你不需要复用，也可以省掉@Named，MapStruct会在当前类里自动寻找合适的转换方法，规则是"方法参数和返回值能对应上就行"。
4. 进阶场景：多源参数、嵌套映射与集合的实测细节
很多项目一开始只做单对象转单对象，但时间一长就会遇到多对象合并、嵌套对象、集合转换、更新已有对象这些复杂场景。MapStruct对这些都是支持的，只是有一些细节需要提前知道，否则会在编译期看到一堆看不懂的报错。
4.1 多个源参数的映射
当目标对象需要从两个甚至更多对象里取值时，可以在Mapper方法里声明多个参数，并通过@Mapping的source指定来源：
@Mapper(componentModel = "spring") public interface OrderMapper { @Mapping(source = "user.userName", target = "userName") @Mapping(source = "order.orderNo", target = "orderNo") OrderVO toVO(User user, Order order); }这里有一个强制约定：当方法有多个源参数时，source里必须用"参数名.属性路径"的格式。不然MapStruct根本分不清这个属性是从哪个对象取的。这也是很多人第一次用多源参数时犯的错。
另外，合并多个对象时，建议把唯一主对象放第一位，这样生成的代码可读性会好一些。user.userName这种写法也支持多级嵌套，比如user.address.city。
4.2 嵌套对象自动映射
如果源对象和目标对象里都有嵌套对象，MapStruct默认能处理一部分。比如：
public class User { private Department department; } public class UserVO { private DepartmentVO department; }只要Department和DepartmentVO字段名能对上，直接写void toVO(User user)，MapStruct就会自动生成一个子映射，把department复制到departmentVO。这个子映射方法也不需要你手写，MapStruct在生成时会临时创建一个私有方法。
但问题往往出在"能对上"这三个字上。假如DepartmentVO里的字段名和Department不一样，或者Department里有个字段在DepartmentVO里不存在，编译期就会报错。解决方式是在方法上额外加@Mapping：
@Mapping(source = "department.deptName", target = "department.name") UserVO toVO(User user);这里需要注意：一旦你在顶层方法上声明了对某个嵌套属性的映射规则，MapStruct就会认为这个嵌套对象你需要精细控制，可能不再自动映射其他同名字段。我在实际使用中遇到过几次"加了一个嵌套映射，其他字段突然不填了"的情况，原因就在这。所以对嵌套对象，要么完全交给MapStruct自动映射，要么就把所有不一致的字段全部显式列出来，不要混着来。
4.3 集合映射
集合映射的写法非常轻量：
List<UserVO> toVOList(List<User> users);MapStruct会自动创建List<UserVO>，然后逐个元素调用toVO方法。如果toVO方法是同接口里定义的同名方法，它甚至不需要额外配置。
稍微复杂一点的是Set、Map这类结构，以及源集合元素类型和目标集合元素类型不一致的情况。比如：
Set<RoleVO> toRoleVOSet(Set<Role> roles);MapStruct会生成一个遍历原集合并调用元素转换的新集合。这里有一个反直觉的坑：Set转换后的顺序不保证，因为Set本身无序，这不是MapStruct能控制的。如果业务上依赖顺序，建议数据源用List。
4.4 更新已有对象：@MappingTarget
MapStruct还支持"把源数据更新到一个已有的目标对象上"，而不是每次new一个新对象。这在编辑业务里非常有用：
@Mapper(componentModel = "spring") public interface UserMapper { void update(UserVO vo, @MappingTarget User user); }调用方式变成了userMapper.update(vo, user)，生成的代码会拿vo里的非null值去覆盖已有user的属性。但这里有个默认行为容易踩坑：MapStruct默认对null值也是覆盖的，也就是说vo.userName为null，它也会把user.userName置为null。
如果希望null值不覆盖、保留目标对象原有值，可以在类级别配：
@Mapper( componentModel = "spring", nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE ) public interface UserMapper { void update(UserVO vo, @MappingTarget User user); }这个策略在生产环境的"部分更新"场景下特别重要。比如前端只传了nickname，没传phone，你肯定不希望phone被置空。用IGNORE策略，源为null的字段就不会被覆盖了。
5. 编译期生成的代码：排查问题最好用的工具
MapStruct和很多框架不一样的地方在于，它是"看得见"的。生成的实现类就躺在target/generated-sources/annotations目录下，如果你遇到莫名其妙的问题，打开这个文件看看，所有谜底都在里面。这个习惯我建议每一个用MapStruct的人都养成。
5.1 生成的实现类在哪
以Maven项目为例，第一次编译后，在IDE的target/generated-sources/annotations目录下，你大概率能找到UserMapperImpl.java。IDEA默认会把它标记为Generated Sources Root，如果你的IDE没显示出来，可能是没有勾选编译开关，重新跑一次mvn compile就能看到。
文件的内容大概长这样：
@Component public class UserMapperImpl implements UserMapper { @Override public UserVO toVO(User user) { if (user == null) { return null; } UserVO userVO = new UserVO(); userVO.setName(user.getUserName()); userVO.setLevel(user.getScore() > 60 ? "PASS" : "FAIL"); return userVO; } }5.2 读一段生成代码
这段生成的代码很有意思。它告诉你几件事：第一，MapStruct确实老老实实调用了getter和setter，没有任何反射魔法；第二，@Mapping的表达式是原样内嵌进去的；第三，源对象为null的时候，方法直接返回null，这是默认的nullValueMappingStrategy。
如果你发现生成代码里的某个字段没有按预期赋值，说明你的@Mapping配得不对，或者字段名压根没对应上。这时候逐行看生成的代码，往往比盯着注解猜更快。比如生成代码里有一行userVO.setName(user.getUserName())，而你预期的字段没出现，那大概率是源对象里没有对应getter。
5.3 常见编译错误怎么定位
MapStruct的报错通常分两类。一类是"找不到映射"：
Can't map property "LocalDateTime birthday" to "String birthdayText". Consider to declare/implement a mapping method意思是MapStruct不知道LocalDateTime怎么转成String，它给了你建议：自己实现一个转换方法，或者用qualifiedByName指定一个。遇到这种错误，我的排查顺序是：先看有没有现成的类型转换方法，没有就加一个@Named方法或者uses转换器。
另一类是"目标属性没有写ignore"：
Unmapped target property: "createTime"如果你设置了unmappedTargetPolicy = ReportingPolicy.ERROR，这类问题会直接让编译失败。解决方式很明确：如果这个字段确实不需要映射，加@Mapping(target = "createTime", ignore = true)；如果需要映射，就补对应的source。
关于编译错误，我还有一个建议：尽量用IDEA自带的编译窗口看，不要只看控制台的前两行。MapStruct经常会把完整错误路径打印出来，比如source: User.getUserName() target: UserVO.name，这种精确到getter和方法名的报错定位性非常强。
6. 实战中的坑与习惯：从代码评审角度给几点建议
使用MapStruct两三年，踩过不少坑，也帮同事review过很多Mapper代码。这里整理几个我认为最值得注意的点，希望能帮你少走弯路。
6.1 与Lombok的搭配
MapStruct和Lombok同时使用时，有一个常见的坑：MapStruct需要生成getter/setter的代码来写映射逻辑，但Lombok的getter/setter是编译期注解处理器生成到源码里的。如果两个处理器的执行顺序不对，MapStruct可能找不到对应的getter/setter方法，导致编译报错。
解决办法是显式声明annotation processor的路径和顺序，在Maven里一般是：
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <annotationProcessorPaths> <path> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>${lombok.version}</version> </path> <path> <groupId>org.projectlombok</groupId> <artifactId>lombok-mapstruct-binding</artifactId> <version>0.2.0</version> </path> <path> <groupId>org.mapstruct</groupId> <artifactId>mapstruct-processor</artifactId> <version>${mapstruct.version}</version> </path> </annotationProcessorPaths> </configuration> </plugin>这个lombok-mapstruct-binding就是官方提供的桥接包，让Lombok先处理完，MapStruct再处理。不配置它，有时候能跑，有时候不能，全看环境心情，不建议碰运气。
6.2 避免在Mapper里塞复杂业务
MapStruct的定位是对象映射，不是业务逻辑引擎。虽然expression、defaultExpression给了你很大的灵活性，但你绝对不想在Mapper的表达式里写一堆复杂的计算、数据库判断、外部服务调用。原因很简单：Mapper方法一旦复杂了，单元测试和代码review都会变得困难。
我的经验是：Mapper里只做字段搬运、简单类型转换、简单默认值处理。复杂的逻辑放在调用Mapper之前的Service层，先算好再传进来，或者干脆在Mapper方法上增加业务参数，而不是用expression把逻辑写进注解。
6.3 注意nullValueMappingStrategy的默认行为
前面提到过，默认情况下，如果源对象为null，MapStruct直接返回null。这在很多场景下是合理的。但如果是"更新已有对象"（@MappingTarget）的映射，null值可能会导致源对象里的null字段覆盖目标对象已有值。这种问题不会编译报错，也不会运行时报错，只会在你看到数据库字段被莫名其妙清空时才发现。
建议对update类方法显式声明：
void update(UserVO vo, @MappingTarget User user);并在类级别或方法级别使用nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE，除非你对"null也要覆盖"确实有需求。
6.4 值得养成的几个习惯
- 一个聚合根对应一个Mapper接口，不要搞一个大而全的万能Mapper。这样每个Mapper职责清晰，也不会出现字段越映射越乱的情况。
- 新增字段时，先看编译输出。把
unmappedTargetPolicy设为ERROR后，编译器会逼着你做选择：映射还是忽略。这个习惯能避免大量"忘了加映射"的隐形Bug。 - 多翻生成的Impl代码。当你对某个行为不确定时，生成代码是最准确的文档。
- 版本升级后重新看生成的代码。MapStruct不同版本之间行为差异不算小，尤其是嵌套策略、默认策略，升级后跑一遍现有测试非常有必要。
回头看看，MapStruct真正打动我的地方不是省了多少行代码，而是它把"字段映射是否正确"从运行期问题提前到了编译期问题。Java是静态类型语言，我们就该充分利用编译器的能力。如果你还没在项目里引入它，我建议找一个边界相对清晰的模块先试起来，配上unmappedTargetPolicy = ERROR，编译报几次错，你应该就能感受到这种"被编译器盯着"的踏实感了。
