MapStruct 详解
GitHub 访问地址 : https://github.com/mapstruct/mapstruct/
使用例子 : https://github.com/mapstruct/mapstruct-examples
MapStrcut与其它工具对比以及使用说明 : http://www.tuicool.com/articles/uiIRjai
BeanUtils.copyProperties 用于对象属性拷贝，会将同名属性拷贝到另外一个对象中，操作方便但是存在一个缺陷
缺陷1> 速度慢
缺陷2> 有些同名字段无法进行特殊化处理，将会导致不想修改的字段被覆盖
在 mvc层 经常会遇到，是否使用 DTO(数据传输对象)，还是直接使用 model返回。前者叫封闭领域模型风格，后者叫开放领域模型风格。因为前者可以排除一些不需要返回的字段但是需要进行拷贝，后者就不需要经过处理。另外，都会遭遇到一种情况 : 如性别在后台是通过0和1，但是需要返回前端男或者女，可以直接使用 DTO 进行数据转换
MapStruct 是用于生成类型安全，高性能和无依赖 bean映射代码的注释处理器，一种类型安全的 bean映射类生成 java注释处理器，使用时只需要定义一个映射器接口来声明任何需要的映射方法。在编译期间，MapStruct 将生成此接口的实现。这个实现使用普通 的Java方法调用来源和目标对象之间的映射，即没有反射或类似。与手写映射代码相比，MapStruct通过生成繁琐且容易出错的代码来节省时间。遵循约定而不是配置方法，MapStruct使用合理的默认值，但在配置或实现特殊行为时不会采取任何步骤
与动态映射框架相比，MapStruct 具有以下优点 :
1> 通过使用普通方法调用而不是反射来快速执行，也就是 会在编译器生成相应的 Impl 方法调用时直接通过简单的 getter/setter调用而不是反射或类似的方式将值从源复制到目标
2> 编译时类型安全性 : 只能映射彼此的对象和属性，不能将订单实体意外映射到客户 DTO等
3> 在构建时清除错误报告，如 映射不完整 (并非所有目标属性都被映射) 或 映射不正确(无法找到适当的映射方法或类型转换)
在进行数据转换时，如果源和目标实体中映射属性的类型不同，则 MapStruct将应用自动转换，或者可选地调用/创建另一个映射方法 (如 : 对于驱动程序/引擎属性)。当且仅当源和目标属性是 Bean属性 并且它们本身是 Bean或简单属性时，MapStruct 才会创建新的映射方法。即他们不是 Collection 或 Map 键入属性。通过创建包含源属性中元素的目标集合类型的新实例，将复制具有相同元素类型的集合类型属性。对于具有不同元素类型的集合类型的属性，每个元素将被单独映射并添加到目标集合中
MapStruct 处理器选项
| 选项 |
目的 |
默认 |
| mapstruct.suppressGeneratorTimestamp |
如果设置为 true ，@Generated 则会在生成的映射器类的注释中创建时间戳 |
false |
| mapstruct.suppressGeneratorVersionInfoComment |
如果设置为 true ，则会在生成的映射器类中注释中的 comment 属性创建 @Generated 被抑制。该注释包含有关 MapStruct版本和用于注释处理的编译器的信息 |
false |
| mapstruct.defaultComponentModel |
根据生成映射器的组件模型的名称，支持的值 : 1> default : 映射器不使用组件模型，通常通过实例检索实例 Mappers#getMapper(Class) 2> cdi : 生成的映射器是一个应用程序范围的CDI bean，可以通过检索 @Inject 3> spring : 生成的映射器是一个单一范围的 Spring bean，可以通过检索 @Autowired 4> jsr330 : 生成的映射器使用 {@code @Named} 进行注释，并且可以通过 @Inject 使用 Spring 进行检索 如果为特定的映射器通过组件模型 @Mapper#componentModel() ，则注释中的值优先 |
default |
| mapstruct.unmappedTargetPolicy |
在映射方法的目标对象的属性未填充源值的情况下应用的默认报告策略，支持的值 : 1> ERROR : 任何未映射的目标属性都将导致映射代码生成失败 2> WARN : 任何未映射的目标属性将在构建时引发警告 3> IGNORE : 未映射的目标属性被忽略 如果为特定的映射器通过了策略 @Mapper#unmappedTargetPolicy() ，则注释中的值优先 |
WARN |
MapStruct 提供的重要注解 :
@Mapper : 标记这个接口作为一个映射接口，并且是编译时 MapStruct 处理器的入口
@Mapping : 解决源对象和目标对象中，属性名字不同的情况
Mappers.getMapper 自动生成的接口的实现可以通过 Mapper 的 class对象获取，从而让客户端可以访问 Mapper接口的实现
基本使用方式 :
在 pom.xml 添加依赖
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd">
...
...
...
常用的接口工具类 : BasicObjectMapper包含了4个基本方法，单个和集合以及反转的单个和集合。开发中如需要对象转换操作可直接新建 interface 并继承 BasicObjectMapper，并在新建的接口上加上 @Mapper(componentModel = "spring")，如果是属性中包含其它类以及该类已经存在 Mapper 则注解中加上 users = {类名.class}。componentModel = "spring" 该配置表示生成的实现类默认加上 spring @Component 注解，使用时可直接通过 @Autowire 进行注入
public interface BasicObjectMapper
@Mappings({})
@InheritConfiguration
TARGET to(SOURCE var1);
@InheritConfiguration
List
@InheritInverseConfiguration
SOURCE from(TARGET var1);
@InheritInverseConfiguration
List
}
直接使用进行对象数据转换
@Data
public class ProductCategory {
/** 类别编码 */
private String categoryCode;
/** 类别名称 */
private String categoryName;
}
@Data
public class CategoryVo {
private String code;
private String name;
}
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Mappings;
import org.mapstruct.factory.Mappers;
@Mapper
public interface CategoryMapper extends BasicObjectMapper
CategoryMapper MAPPER = Mappers.getMapper(CategoryMapper.class);
@Mappings({
@Mapping(source = "code", target = "categoryCode"),
@Mapping(source = "name", target = "categoryName")
})
ProductCategory to(CategoryVo source);
}
# 进行测试
public static void main(String[] args) {
CategoryMapper categoryMapper = CategoryMapper.MAPPER;
CategoryVo vo = new CategoryVo();
vo.setCode("0000");
vo.setName("属性名称");
ProductCategory pc = categoryMapper.to(vo); // 通过 to方法得到 ProductCategory
System.out.println("1" + pc);
CategoryVo vo1 = categoryMapper.from(pc); // 通过 from方法得到 CategoryVo，既反转 to方法
System.out.println("2" + vo1);
List
System.out.println("3" + pcList);
List
System.out.println("4" + voList);
}
最后使用 mvn compile 指令生成映射器的实现类
自定义方法添加到映射器 : 在某些情况下，需要手动实现 MapStruct 无法生成的从一种类型到另一种类型的特定映射，有如下两种实现方法 :
方法1> 在另一个类上实现此类方法，然后由 MapStruct 生成的映射器使用该方法
方法2> 在Java 8或更高版本时，可以直接在映射器界面中实现自定义方法作为默认方法。如果参数和返回类型匹配，生成的代码将调用默认方法
@Mapper
public interface CarMapper {
@Mappings({...})
CarDto carToCarDto(Car car);
default PersonDto personToPersonDto(Person person) {
// hand-written mapping logic
}
}
映射器也可以定义为抽象类的形式而不是接口，并直接在此映射器类中实现自定义方法。在这种情况下，MapStruct将生成抽象类的扩展，并实现所有抽象方法。这种方法优于声明默认方法的优点是可以在映射器类中声明附加字段
@Mapper
public abstract class CarMapper {
@Mappings(...)
public abstract CarDto carToCarDto(Car car);
public PersonDto personToPersonDto(Person person) {
// hand-written mapping logic
}
}
多源参数映射方法 : MapStruct 支持多个源参数的映射方法，将几个实体组合成一个数据传输对象
@Mapper
public interface AddressMapper {
@Mappings({
@Mapping(source = "person.description", target = "description"),
@Mapping(source = "address.houseNo", target = "houseNumber")
})
DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Address address);
}
如果多个源对象定义了一个具有相同名称的属性，则必须使用 @Mapping 注释来指定从中检索属性的源参数，如果这种歧义未得到解决，将会引发错误。对于在给定源对象中只存在一次的属性，指定源参数的名称是可选的，因为它可以自动确定
MapStruct 还提供直接引用源参数
@Mapper
public interface AddressMapper {
@Mappings({
@Mapping(source = "person.description", target = "description"),
@Mapping(source = "hn", target = "houseNumber")
})
DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Integer hn);
}
更新现有 bean : 有时需要映射不创建目标类型的新实例，而是更新该类型的现有实例。这种映射可以通过为目标对象添加一个参数并用该参数标记来实现 @MappingTarget
@Mapper
public interface CarMapper {
void updateCarFromDto(CarDto carDto, @MappingTarget Car car);
}
还可以设置方法的返回类型为目标参数的类型，这将导致生成的实现来更新通过映射目标并返回它
直接字段访问映射 : MapStruct 支持 public 没有 getter/setter 的字段的映射，如果 MapStruct 无法为属性找到合适的 getter/setter方法，MapStruct 将使用这些字段作为 读/写访问器。如果它是 public，则字段被认为是读取存取器 public final。如果一个字段 static 不被视为读取存取器只有在字段被认为是写入访问者的情况下 public。如果一个字段 final 和/或 static 它不被认为是写入访问者
public class Customer {
private Long id;
private String name;
// getters and setter omitted for brevity
}
public class CustomerDto {
public Long id;
public String customerName;
}
@Mapper
public interface CustomerMapper {
CustomerMapper MAPPER = Mappers.getMapper( CustomerMapper.class );
@Mapping(source = "customerName", target = "name")
Customer toCustomer(CustomerDto customerDto);
@InheritInverseConfiguration
CustomerDto fromCustomer(Customer customer);
}
生成的映射器如下
public class CustomerMapperImpl implements CustomerMapper {
@Override
public Customer toCustomer(CustomerDto customerDto) {
// ...
customer.setId( customerDto.id );
customer.setName( customerDto.customerName );
// ...
}
@Override
public CustomerDto fromCustomer(Customer customer) {
// ...
customerDto.id = customer.getId();
customerDto.customerName = customer.getName();
// ...
}
}
检索映射器 : Mapper实例 通过 org.mapstruct.factory.Mappers 的 getMapper() 方法来检索。通常 映射器接口应该定义一个名为的成员 INSTANCE ，它包含一个映射器类型的单个实例 :
@Mapper
public interface CarMapper {
CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
CarDto carToCarDto(Car car);
}
这种模式使客户非常容易地使用映射器对象，而无需反复实例化新的实例 :
Car car = ...;
CarDto dto = CarMapper.INSTANCE.carToCarDto( car );
使用依赖注入 : 通过 Spring 依赖注入可以获取映射器对象
@Mapper(componentModel = "spring")
public interface CarMapper {
CarDto carToCarDto(Car car);
}
@Inject
private CarMapper mapper;
数据类型转换 : 源对象和目标对象中映射的属性类型可能不同，MapStruct 提供自动处理类型转换，提供如下自动转换 :
1> Java基本数据类型及其相应的包装类型，如 int 和 Integer，boolean 和 Boolean 等生成的代码是 null 转换一个包装型成相应的原始类型时一个感知，即 null 检查将被执行
2> Java基本号码类型和包装类型，例如之间 int 和 long 或 byte 和 Integer (大类类型数据转换成小类可能出现精度损失)
3> 所有Java基本类型之间 (包括其包装) 和 String 之间，例如 int 和 String 或 Boolean 和 String，java.text.DecimalFormat 均可以指定格式字符串
int 到 String的转换
@Mapper
public interface CarMapper {
@Mapping(source = "price", numberFormat = "$#.00")
CarDto carToCarDto(Car car);
@IterableMapping(numberFormat = "$#.00")
List
}
BigDecimal 转换为 String
@Mapper
public interface CarMapper {
@Mapping(source = "power", numberFormat = "#.##E0")
CarDto carToCarDto(Car car);
}
从日期到字符串的转换
@Mapper
public interface CarMapper {
@Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
CarDto carToCarDto(Car car);
@IterableMapping(dateFormat = "dd.MM.yyyy")
List
}
映射对象引用 : 对象中如果包含另一个对象的引用，此时只需为引用的对象类型定义映射方法即可
@Mapper
public interface CarMapper {
CarDto carToCarDto(Car car);
PersonDto personToPersonDto(Person person);
}
# 映射器控制嵌套的bean映射
@Mapper
public interface FishTankMapper {
@Mappings({
@Mapping(target = "fish.kind", source = "fish.type"),
@Mapping(target = "fish.name", ignore = true),
@Mapping(target = "plant", ignore = true ),
@Mapping(target = "ornament", ignore = true ),
@Mapping(target = "material", ignore = true),
@Mapping(target = "ornament", source = "interior.ornament"),
@Mapping(target = "material.materialType", source = "material"),
@Mapping(target = "quality.report.organisation.name", source = "quality.report.organisationName")
})
FishTankDto map( FishTank source );
}
调用其他映射器 : MapStruct 中可以调用在其他类中定义的映射方法，无论是由MapStruct生成的映射器还是手写映射方法
# 手动实现的映射
public class DateMapper {
public String asString(Date date) {
return date != null ? new SimpleDateFormat("yyyy-MM-dd").format(date) : null;
}
public Date asDate(String date) {
try {
return date != null ? new SimpleDateFormat("yyyy-MM-dd").parse(date) : null;
} catch (ParseException e) {
throw new RuntimeException(e);
}
}
}
# 引用另一个映射器类
@Mapper(uses = DateMapper.class)
public class CarMapper {
CarDto carToCarDto(Car car);
}
当为该 carToCarDto() 方法的实现生成代码时，MapStruct将查找将 Date 对象映射到String的方法，在 DateMapper 该类上找到它并生成 asString() 用于映射该 manufacturingDate 属性的调用
映射集合 : 集合类型(映射 List，Set 等等) 以相同的方式映射 bean类型，通过定义与在映射器接口所需的源和目标类型的映射方法。生成的代码将包含一个遍历源集合的循环，转换每个元素并将其放入目标集合中。如果在给定的映射器或其使用的映射器中找到了集合元素类型的映射方法，则会调用此方法以执行元素转换。或者，如果存在源和目标元素类型的隐式转换，则将调用此转换例程
@Mapper
public interface CarMapper {
Set
List
CarDto carToCarDto(Car car);
}
# 生成的集合映射方法
@Override
public Set
if (integers == null) {
return null;
}
Set
for (Integer integer : integers) {
set.add(String.valueOf(integer));
}
return set;
}
@Override
public List
if (cars == null) {
return null;
}
List
for (Car car : cars) {
list.add(carToCarDto(car));
}
return list;
}
映射Map :
public interface SourceTargetMapper {
@MapMapping(valueDateFormat = "dd.MM.yyyy")
Map
}
映射流 :
@Mapper
public interface CarMapper {
Set
List
CarDto carToCarDto(Car car);
}
映射枚举 : 默认情况下，源枚举中的每个常量映射到目标枚举类型中具有相同名称的常量。如果需要，可以使用 @ValueMapping 注释帮助将source enum中的常量映射为具有其他名称的常量
@Mapper
public interface OrderMapper {
OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);
@ValueMappings({
@ValueMapping(source = "EXTRA", target = "SPECIAL"),
@ValueMapping(source = "STANDARD", target = "DEFAULT"),
@ValueMapping(source = "NORMAL", target = "DEFAULT")
})
ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
}
默认值和常量 :
@Mapper(uses = StringListMapper.class)
public interface SourceTargetMapper {
SourceTargetMapper INSTANCE = Mappers.getMapper(SourceTargetMapper.class);
@Mappings({
@Mapping(target = "stringProperty", source = "stringProp", defaultValue = "undefined"),
@Mapping(target = "longProperty", source = "longProp", defaultValue = "-1"),
@Mapping(target = "stringConstant", constant = "Constant Value"),
@Mapping(target = "integerConstant", constant = "14"),
@Mapping(target = "longWrapperConstant", constant = "3001"),
@Mapping(target = "dateConstant", dateFormat = "dd-MM-yyyy", constant = "09-01-2014"),
@Mapping(target = "stringListConstants", constant = "jack-jill-tom")
})
Target sourceToTarget(Source s);
}
表达式 :
@Mapper
public interface SourceTargetMapper {
SourceTargetMapper INSTANCE = Mappers.getMapper(SourceTargetMapper.class);
@Mapping(target = "timeAndFormat", expression = "java( new org.sample.TimeAndFormat( s.getTime(), s.getFormat() ) )")
Target sourceToTarget(Source s);
}
确定结果类型 : 当结果类型具有继承关系时，选择映射方法(@Mapping) 或工厂方法(@BeanMapping) 可能变得不明确。假设一个Apple和一个香蕉，这两个都是 Fruit的专业
@Mapper(uses = FruitFactory.class)
public interface FruitMapper {
@BeanMapping(resultType = Apple.class)
Fruit map(FruitDto source);
}
public class FruitFactory {
public Apple createApple() {
return new Apple("Apple");
}
public Banana createBanana() {
return new Banana("Banana");
}
}
控制 '空' 参数的映射结果 : 默认情况下 null 会返回，通过指定 nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT 上 @BeanMapping，@IterableMapping，@MapMapping，或全局上 @Mapper 或 @MappingConfig，映射结果可以被改变以返回空默认值
1> Bean映射 : 将返回一个 '空' 目标bean，除常量和表达式外，它们将在存在时填充
2> 基元 : 基元的默认值将被返回，例如 false for boolean 或 0 for int
3> Iterables/Arrays : 一个空的迭代器将被返回
4> 地图 : 将返回空白地图
共享配置 : 通过指向中心接口来定义共享配置的可能性 @MapperConfig，要使映射器使用共享配置，需要在 @Mapper#config 属性中定义配置界面。该 @MapperConfig 注释具有相同的属性 @Mapper 注释。任何未通过的属性 @Mapper 都将从共享配置继承。指定 @Mapper 的属性优先于通过引用的配置类指定的属性
@MapperConfig(uses = CustomMapperViaMapperConfig.class, unmappedTargetPolicy = ReportingPolicy.ERROR)
public interface CentralConfig {}
@Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
public interface SourceTargetMapper {}