MapStruct 使用姿势

背景

在代码开发中,我们通常都会使用分层架构,在分层架构中都会使用模型转换,在不同的层使用不同的模型。以 DDD 分层模型为例,如下:


image.png

模型分类

DO

DataObject,数据库映射对象,通常用于基础设施层,与数据库字段完全对应。

Entity

领域对象,通常用于应用层和领域层(有一些 DDD 代码模型在应用层使用的是 DTO,但是基于应用层是业务编排的职责,可能会直接使用 Entity 的行为进行逻辑编排,那么个人建议应用层应该使用 Entity)。不只是指实体、还包括值对象。通常是充血模型,包括属性和行为。

DTO

数据传输对象,通常用于用户接口层(用户接口层,通常指的是流量入口,包括web 流量、服务消费者 RPC 调用、消息输入等)。所以 DTO 通常用于Controller中的输入输出参数、打到二方包里的输入输出参数(例如,Dubbo 接口的输入输出参数)以及消息消费者中的消息模型。
根据实际需要,有时候在 web 中,我们也会使用 vo。

转换器

DTOAssembler

DTO 和 Entity 的转换器

DOConverter

DO 和 Entity 的转换器

现有 Bean 转换工具的比较

目前的转化器有:手写转换器、Apache BeanUtils、Spring BeanUtils、Dozer、Orika、ModelMapper、JMapper、MapStruct 等。其中手写转换器带来的人工成本较高,尤其是当转换对象属性较多,或者有嵌套属性时,费时费力,且容易遗漏出错,而且随着对象的迭代,转换器中的代码也要变动,所以通常我们还是会采用自动化的转换器。
根据 这篇文章 的性能压测来看,JMapper 和 MapStruct 的性能最好,根据易用性来讲 MapStruct 最好,所以我们就使用 MapStruct 来实现转换器。

MapStruct 使用

    
        1.4.1.Final
    

    
        
        
            org.mapstruct
            mapstruct
            ${org.mapstruct.version}
        
        
        
            org.mapstruct
            mapstruct-processor
            ${org.mapstruct.version}
            provided
        
        
        
            org.projectlombok
            lombok
            1.18.16
            provided
        
        
        
            org.projectlombok
            lombok-mapstruct-binding
            0.2.0
            provided
        
    

    
        
            
                org.apache.maven.plugins
                maven-compiler-plugin
                3.8.1
                
                    1.8
                    1.8
                
            
        
    

最简示例

DTO & Entity

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String name;
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private String name;
}

转换类

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

测试类

public class Test {
    public static void main(String[] args) {
        testFromSource();
        testToSource();
    }

    private static void testFromSource(){
        Source source = new Source(1, "测试基础转换");
        Target target = Converter.INSTANCE.fromSource(source);
        System.out.println(target);
    }

    private static void testToSource(){
        Target target = new Target(1, "测试基础转换");
        Source source = Converter.INSTANCE.toSource(target);
        System.out.println(source);
    }
}

不同名称的属性关联

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String name; // 映射 Target 中的 targetName
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private String targetName; // 映射 Source 中的 name
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);

    @Mapping(source = "name", target = "targetName")
    Target fromSource(Source source);

    @InheritInverseConfiguration
    Source toSource(Target target);
}
  1. 使用 @Mapping 手动映射属性;
  2. 使用 @InheritInverseConfiguration 表示继承反方向的配置,例如,上例中的 toSource 方法的注解可以硬编码为 @Mapping(source = "targetName", target = "name"),效果相同

不同类型的属性关联

@Data
@AllArgsConstructor
public class Source {
    private Integer id; // 对应 Target 的 Long id
    private String price; // 对应 Target 的 Double price
}

@Data
@AllArgsConstructor
public class Target {
    private Long id;
    private Double price;
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

属性名相同的属性如果类型不同,会直接进行类型自动转换

内嵌属性关联

@Data
@AllArgsConstructor
public class Source {
    private Integer id; // 对应 Target.TargetId.id
    private String name;
}

@Data
@AllArgsConstructor
public class Target {
    private TargetId targetId;
    private String name;
}

@Data
@AllArgsConstructor
public class TargetId {
    private Integer id;

    public static TargetId of(Integer id) {
        if (id == null) {
            throw new RuntimeException("id 不能为 null");
        }
        return new TargetId(id);
    }
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);

    @Mapping(source = "id", target = "targetId.id")
    Target fromSource(Source source);

    @InheritInverseConfiguration
    Source toSource(Target target);
}

直接在 Mapping 中做属性嵌套转换

枚举类关联(属性抽取)

简单枚举类

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String type;
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private SimpleEnumType type;
}

public enum SimpleEnumType {
    HAHA, HEHE
}
or
public enum SimpleEnumType {
    HAHA("HAHA"), HEHE("HEHE");

    private String desc;

    SimpleEnumType(String desc) {
        this.desc = desc;
    }
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

简单枚举类:单个参数的枚举类会自动进行类型转换

复杂枚举类

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String name; // 映射 Target.targetName
    private Integer typeCode; // 映射 Target.type.code
    private String typeName; // 映射 Target.type.name
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private String targetName;
    private ComplexEnumType type;
}

@Getter
public enum ComplexEnumType {
    HAHA(1, "haha"), HEHE(2, "hehe");

    private Integer code;
    private String name;

    ComplexEnumType(Integer code, String name) {
        this.code = code;
        this.name = name;
    }

    public static ComplexEnumType getByCode(Integer code) {
        return Arrays.stream(values()).filter(x->x.getCode().equals(code)).findFirst().orElse(null);
    }
}

Java 表达式

@Mapper
public interface ConverterWithExpression {
    ConverterWithExpression INSTANCE = Mappers.getMapper(ConverterWithExpression.class);

    @Mapping(source = "name", target = "targetName")
    @Mapping(target = "type", expression = "java(ComplexEnumType.getByCode(source.getTypeCode()))")
    Target fromSource(Source source);

    @InheritInverseConfiguration
    @Mapping(target = "typeCode", source = "type.code")
    @Mapping(target = "typeName", source = "type.name")
    Source toSource(Target target);
}
  1. expression:格式:java(xxx),其中的 xxx 是 Java 语法,其计算出来的值会填充到 target 中。当 IDEA 安装了 MapStruct Support 插件时,在编写 xxx 时会有提示。上述的 toSource 直接使用了嵌套属性获取方式,也可以使用 @Mapping(target = "typeName", expression = "java(target.getType().getName())") 这样的格式。
  2. @InheritInverseConfiguration:特殊值特殊处理,比如这里的枚举相关值,其他属性依旧使用逆转继承即可。

Qualifier 注解

import org.mapstruct.Qualifier;
public class ComplexEnumTypeUtil {
    @Qualifier
    @Target(ElementType.METHOD)
    @Retention(RetentionPolicy.SOURCE)
    public @interface TypeCode {
    }

    @Qualifier
    @Target(ElementType.METHOD)
    @Retention(RetentionPolicy.SOURCE)
    public @interface TypeName {
    }

    @TypeCode
    public Integer typeCode(ComplexEnumType type) {
        return type.getCode();
    }

    @TypeName
    public String typeName(ComplexEnumType type) {
        return type.getName();
    }
}

@Mapper(uses = ComplexEnumTypeUtil.class)
public interface ConverterWithQualifier {
    ConverterWithQualifier INSTANCE = Mappers.getMapper(ConverterWithQualifier.class);

    @Mapping(source = "name", target = "targetName")
    @Mapping(target = "type", expression = "java(ComplexEnumType.getByCode(source.getTypeCode()))")
    Target fromSource(Source source);

    @InheritInverseConfiguration
    @Mapping(source = "type", target = "typeCode", qualifiedBy = ComplexEnumTypeUtil.TypeCode.class)
    @Mapping(source = "type", target = "typeName", qualifiedBy = ComplexEnumTypeUtil.TypeName.class)
    Source toSource(Target target);
}

转换类上 @Mapper(uses ={xxx.class} 可以指定使用的转换辅助类

Name 注解

@Mapper
public interface ConverterWithName {
    ConverterWithName INSTANCE = Mappers.getMapper(ConverterWithName.class);

    @Mapping(source = "name", target = "targetName")
    @Mapping(target = "type", expression = "java(ComplexEnumType.getByCode(source.getTypeCode()))")
    Target fromSource(Source source);

    @InheritInverseConfiguration
    @Mapping(source = "type", target = "typeCode", qualifiedByName = "typeCodeUtil")
    @Mapping(source = "type", target = "typeName", qualifiedByName = "typeNameUtil")
    Source toSource(Target target);

    @Named("typeCodeUtil")
    default Integer typeCode(ComplexEnumType type) {
        return type.getCode();
    }

    @Named("typeNameUtil")
    default String typeName(ComplexEnumType type) {
        return type.getName();
    }
}

三种方式:Java Expression 最简单,推荐使用

null 值映射时忽略或者填充默认值

@Mapper(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

nullValuePropertyMappingStrategy 的解释

public enum NullValuePropertyMappingStrategy {

    /**
     * If a source bean property equals {@code null} the target bean property will be set explicitly to {@code null}.
     */
    SET_TO_NULL,

    /**
     * If a source bean property equals {@code null} the target bean property will be set to its default value.
     * 

* This means: *

    *
  1. For {@code List} MapStruct generates an {@code ArrayList}
  2. *
  3. For {@code Map} a {@code HashMap}
  4. *
  5. For arrays an empty array
  6. *
  7. For {@code String} {@code ""}
  8. *
  9. for primitive / boxed types a representation of {@code 0} or {@code false}
  10. *
  11. For all other objects an new instance is created, requiring an empty constructor.
  12. *
*

* Make sure that a {@link Mapping#defaultValue()} is defined if no empty constructor is available on * the default value. */ SET_TO_DEFAULT, /** * If a source bean property equals {@code null} the target bean property will be ignored and retain its * existing value. */ IGNORE; }

指定不映射某些值

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String name;
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private String name;
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);

    // name 值不做映射
    @Mapping(source = "name", target = "name", ignore = true)
    Target fromSource(Source source);

    @InheritInverseConfiguration
    Source toSource(Target target);
}

通过 @Mapping#ignore=true 来指定不需要做映射的值

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private List itemList;
}

@Data
@AllArgsConstructor
public class SourceItem {
    private String identifier;
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private List itemList;
}

@Data
@AllArgsConstructor
public class TargetItem {
    private String identifier;
}

@Mapper
public interface SourceItemConverter {
    SourceItemConverter INSTANCE = Mappers.getMapper(SourceItemConverter.class);
    TargetItem fromSourceItem(SourceItem sourceItem);
    SourceItem toSourceItem(TargetItem targetItem);
}

@Mapper
public interface SourceConverter {
    SourceConverter INSTANCE = Mappers.getMapper(SourceConverter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

public class Test {
    public static void main(String[] args) {
        testFromSource();
        testToSource();
    }

    private static void testFromSource(){
        Target target = SourceConverter.INSTANCE.fromSource(new Source(1, Arrays.asList(new SourceItem("111"), new SourceItem("112"))));
        System.out.println(target);
    }

    private static void testToSource(){
        Source source = SourceConverter.INSTANCE.toSource(new Target(2, Arrays.asList(new TargetItem("222"), new TargetItem("223"))));
        System.out.println(source);
    }
}

各写各的映射器,应用的时候是需要调用最外层的映射器即可。

更新目标类而不是新建目标类

@Data
@AllArgsConstructor
public class Source {
    private Integer id;
    private String name;
}

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private String name;
}

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);

    /**
     * id 不做更新,其他 source 的属性更新到 target
     * @param source
     * @param target
     */
    @Mapping(target = "id", ignore = true)
    void fromSource(Source source, @MappingTarget Target target);
}

public class Test {
    public static void main(String[] args) {
        testFromSource();
    }

    private static void testFromSource(){
        Source source = new Source(1, "sourceName");
        Target target = new Target(2, "targetName");
        Converter.INSTANCE.fromSource(source, target);
        System.out.println(target);
    }
}

MapStruct 原理

以上述的最简示例为例,在项目编译时,会把如下转换接口动态编译出实现类(底层使用了 APT 技术,APT 示例见这里)。实现类与手写的转换器类似,使用构造器或者 setter/getter 进行操作。
在运行时,直接执行该实现类,所以性能与手写几乎相同。

@Mapper
public interface Converter {
    Converter INSTANCE = Mappers.getMapper(Converter.class);
    Target fromSource(Source source);
    Source toSource(Target target);
}

其实现类如下:

package xxx; // 与接口所在的包名相同

import javax.annotation.Generated;

@Generated(
    value = "org.mapstruct.ap.MappingProcessor",
    date = "2021-01-21T21:19:02+0800",
    comments = "version: 1.4.1.Final, compiler: javac, environment: Java 1.8.0_151 (Oracle Corporation)"
)
public class ConverterImpl implements Converter {

    @Override
    public Target fromSource(Source source) {
        if ( source == null ) {
            return null;
        }

        Integer id = null;
        String name = null;

        id = source.getId();
        name = source.getName();

        Target target = new Target( id, name );

        return target;
    }

    @Override
    public Source toSource(Target target) {
        if ( target == null ) {
            return null;
        }

        Integer id = null;
        String name = null;

        id = target.getId();
        name = target.getName();

        Source source = new Source( id, name );

        return source;
    }
}

你可能感兴趣的:(MapStruct 使用姿势)