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);
}

使用 @Mapping 手动映射属性；

使用 @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);
}

expression：格式：java(xxx)，其中的 xxx 是 Java 语法，其计算出来的值会填充到 target 中。当 IDEA 安装了 MapStruct Support 插件时，在编写 xxx 时会有提示。上述的 toSource 直接使用了嵌套属性获取方式，也可以使用 @Mapping(target = "typeName", expression = "java(target.getType().getName())") 这样的格式。

@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;
    }
}

最后编辑于：2021.02.12 14:13:03

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 160,026评论 4赞 364
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 67,655评论 1赞 296
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 109,726评论 0赞 244
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 44,204评论 0赞 213
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 52,558评论 3赞 287
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 40,731评论 1赞 222
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 31,944评论 2赞 314
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 30,698评论 0赞 203
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 34,438评论 1赞 246
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 30,633评论 2赞 247
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 32,125评论 1赞 260
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 28,444评论 3赞 255
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 33,137评论 3赞 238
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 26,103评论 0赞 8
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 26,888评论 0赞 197
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 35,772评论 2赞 276
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 35,669评论 2赞 271