java map 内置类型,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);

}

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

*

* This means:

*

*

For {@code List} MapStruct generates an {@code ArrayList}

*

For {@code Map} a {@code HashMap}

*

For arrays an empty array

*

For {@code String} {@code ""}

*

for primitive / boxed types a representation of {@code 0} or {@code false}

*

For all other objects an new instance is created, requiring an empty constructor.

*

*

* 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;

}

}