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 使用

    <properties>
        <org.mapstruct.version>1.4.1.Final</org.mapstruct.version>
    </properties>

    <dependencies>
        <!-- mapStruct 核心注解 -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
        </dependency>
        <!-- mapStruct 根据接口生成实现类 -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct-processor</artifactId>
            <version>${org.mapstruct.version}</version>
            <scope>provided</scope>
        </dependency>
        <!-- lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.16</version>
            <scope>provided</scope>
        </dependency>
        <!-- mapStruct 支持 lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-mapstruct-binding</artifactId>
            <version>0.2.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

最简示例

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.
     * <p>
     * This means:
     * <ol>
     * <li>For {@code List} MapStruct generates an {@code ArrayList}</li>
     * <li>For {@code Map} a {@code HashMap}</li>
     * <li>For arrays an empty array</li>
     * <li>For {@code String} {@code ""}</li>
     * <li>for primitive / boxed types a representation of {@code 0} or {@code false}</li>
     * <li>For all other objects an new instance is created, requiring an empty constructor.</li>
     * </ol>
     * <p>
     * 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<SourceItem> itemList;
}

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

@Data
@AllArgsConstructor
public class Target {
    private Integer id;
    private List<TargetItem> 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;
    }
}
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

推荐阅读更多精彩内容