SpringBoot中如何用JsonProperty/JsonAlias实现MapStruct字段映射？

MapStruct 从1.4版本开始支持识别Jackson的@JsonProperty和@JsonAlias注解来自动关联源对象与目标对象的字段，完全不需要逐个编写@Mapping注解，非常适合你这种字段数量多且名称完全不同的场景。

实现步骤与示例 #

1. 确保依赖齐全 #

在你的Spring Boot项目中，添加MapStruct核心依赖、注解处理器，以及Spring Web（自带Jackson）：

<!-- MapStruct 核心依赖 -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<!-- MapStruct 注解处理器（编译时生成映射实现类） -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
    <scope>provided</scope>
</dependency>
<!-- Spring Boot Web（自带Jackson依赖） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 标记源/目标对象的字段映射 #

你可以选择两种方式标记字段关联：

方式一：在源对象字段上用@JsonProperty指定目标字段名

import com.fasterxml.jackson.annotation.JsonProperty;

public class SourceEntity {
    // 源字段srcUserName 对应 目标字段targetUserName
    @JsonProperty("targetUserName")
    private String srcUserName;

    // 源字段srcAge 对应 目标字段targetAge
    @JsonProperty("targetAge")
    private Integer srcAge;

    // 其余700+字段按此规则添加@JsonProperty标记
    // 省略getter/setter
}

目标对象只需保持字段名与@JsonProperty指定的名称一致：

public class TargetDTO {
    private String targetUserName;
    private Integer targetAge;

    // 其余700+字段名称与源对象@JsonProperty指定的名称对应
    // 省略getter/setter
}

方式二：在目标对象字段上用@JsonAlias指定源字段名

import com.fasterxml.jackson.annotation.JsonAlias;

public class TargetDTO {
    // 目标字段targetUserName 对应 源字段srcUserName
    @JsonAlias("srcUserName")
    private String targetUserName;

    // 目标字段targetAge 对应 源字段srcAge
    @JsonAlias("srcAge")
    private Integer targetAge;

    // 其余700+字段按此规则添加@JsonAlias标记
    // 省略getter/setter
}

源对象保持原有字段名即可：

public class SourceEntity {
    private String srcUserName;
    private Integer srcAge;

    // 其余700+字段保持原有名称
    // 省略getter/setter
}

3. 编写MapStruct映射接口 #

无需添加任何@Mapping注解，只需配置Mapper启用Spring组件模型和Jackson集成：

import org.mapstruct.Mapper;
import org.mapstruct.MappingConstants;
import org.mapstruct.ReportingPolicy;

@Mapper(
        componentModel = MappingConstants.ComponentModel.SPRING,
        unmappedTargetPolicy = ReportingPolicy.IGNORE, // 可选：忽略未映射的字段，避免编译警告
        uses = org.mapstruct.extensions.spring.SpringAdapter.class // 启用Jackson注解识别
)
public interface ObjectConverter {
    // 自动根据Jackson注解完成字段映射
    TargetDTO convertToTarget(SourceEntity source);
}

4. 测试映射效果 #

在Spring Boot中注入映射接口即可使用：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class MappingTest implements CommandLineRunner {

    @Autowired
    private ObjectConverter converter;

    @Override
    public void run(String... args) {
        SourceEntity source = new SourceEntity();
        source.setSrcUserName("张三");
        source.setSrcAge(25);

        TargetDTO target = converter.convertToTarget(source);
        System.out.println(target.getTargetUserName()); // 输出：张三
        System.out.println(target.getTargetAge()); // 输出：25
    }
}

注意事项 #

• 建议使用MapStruct 1.5.x及以上版本，对Jackson注解的支持更稳定。
• 如果存在字段类型不匹配的情况，MapStruct会自动尝试基础类型转换；复杂类型需自定义转换器。
• 可以混合使用@JsonProperty和@JsonAlias，也可以对个别特殊字段单独添加@Mapping注解，两者不会冲突。

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