mapstruct-plus/docs/guide/configuration.md

title, order, category, description

title	order	category	description
配置项	6	指南	MapStructPlus MapStructPlus配置项 configuration

MapStructPlus 提供了多个配置项，来指定生成转换接口时的一些行为。

使用方式

在需要进行配置的模块中，新建配置类，在该类上面增加注解：@MapperConfig，在一个模块中，只能有一个有该注解的类。 同时，还要注意配置类一定要放在要生效的模块中

例如：

@MapperConfig(adapterClassName = "DemoConvertMapperAdapter",
    adapterPackage = "io.github.linpeilie.adapter",
    mapAdapterClassName = "DemoMapConvertMapperAdapter")
public class MapStructPlusConfiguration {
}

:::info

1.3.2 已彻底适配 IDEA 部分编译，无需再添加如下配置。

~~当使用该方式配置时，强烈建议，在编译参数中，指定配置类为当前类，以解决IDEA部分编译场景时出现的各种问题，该功能从 1.3.1 开始支持

配置时，需要在启动参数中添加 -Amapstruct.plus.mapperConfigClass 参数，该参数的值为配置类的全路径名称~~：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.8.0</version>
  <configuration>
    <source>${maven.compiler.source}</source>
    <target>${maven.compiler.target}</target>
    <annotationProcessorPaths>
      <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
      </path>
      <path>
        <groupId>io.github.linpeilie</groupId>
        <artifactId>mapstruct-plus-processor</artifactId>
        <version>${mapstruct-plus.version}</version>
      </path>
      <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok-mapstruct-binding</artifactId>
        <version>0.2.0</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-Amapstruct.plus.mapperConfigClass=com.tutelary.MapStructPlusConfiguration</arg>
    </compilerArgs>
  </configuration>
</plugin>

:::

---

除此之外，配置属性还支持增加编译参数的方式，以 -Akey=value 的形式，传递给编译器。

例如，使用 Maven 时，可以在 maven-compiler-plugin 插件配置中，使用 compilerArgs 属性来配置传递，例如：

且使用该方式配置优先级更高，即，当该方式和配置类同时存在时，以该方式配置的属性为准。该功能从 1.3.0 开始支持。

示例：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.0</version>
      <configuration>
        <source>${maven.compiler.source}</source>
        <target>${maven.compiler.target}</target>
        <annotationProcessorPaths>
          <path>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
          </path>
          <path>
            <groupId>io.github.linpeilie</groupId>
            <artifactId>mapstruct-plus-processor</artifactId>
            <version>${mapstruct-plus.version}</version>
          </path>
          <path>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-mapstruct-binding</artifactId>
            <version>0.2.0</version>
          </path>
        </annotationProcessorPaths>
        <compilerArgs>
          <arg>-Amapstruct.plus.adapterClassName=DemoConvertMapperAdapter</arg>
          <arg>-Amapstruct.plus.adapterPackage=io.github.linpeilie.adapter</arg>
          <arg>-Amapstruct.plus.mapAdapterClassName=DemoMapConvertMapperAdapter</arg>
        </compilerArgs>
      </configuration>
    </plugin>
  </plugins>
</build>

配置项

mapperPackage

• 说明：生成的 Mapper 转换接口的包名
• 类型：String
• 默认值：默认生成在要转换的类同包名下
• 对应编译参数：-Amapstruct.plus.mapperPackage

unmappedSourcePolicy

• 说明：当来源类中没有对应属性时的策略，默认忽略
• 类型：ReportingPolicy
• 可选项：
  • IGNORE：忽略
  • WARN：打印警告日志
  • ERROR：抛出异常
• 默认值：IGNORE
• 对应编译参数：-Amapstruct.plus.unmappedSourcePolicy

unmappedTargetPolicy

• 说明：当目标类中没有对应属性时的策略，默认忽略
• 类型：ReportingPolicy
• 可选项：
  • IGNORE：忽略
  • WARN：打印警告日志
  • ERROR：抛出异常
• 默认值：IGNORE
• 对应编译参数：-Amapstruct.plus.unmappedTargetPolicy

nullValueMappingStrategy

• 说明：空值对象处理策略，默认返回空值
• 类型：NullValueMappingStrategy
• 可选项：
  • RETURN_NULL：返回空值
  • RETURN_DEFAULT：返回默认值
• 默认值：RETURN_NULL
• 对应编译参数：-Amapstruct.plus.nullValueMappingStrategy

nullValuePropertyMappingStrategy

• 说明：当属性值为 null 时应对的策略，默认设置 null
• 类型：NullValuePropertyMappingStrategy
• 可选项：
  • SET_TO_NULL：设置为 null
  • SET_TO_DEFAULT：设置为默认值
  • IGNORE：忽略
• 默认值：SET_TO_NULL
• 对应编译参数：-Amapstruct.plus.nullValuePropertyMappingStrategy

builder

• 说明：构造者模式配置，MapStruct 与 lombok 的 builder 一起使用时，会丢失父类属性，所以这里将默认使用构造者模式关闭
• 类型：Builder
• 支持配置项：
  • buildMethod：构造器创建要构建类型时的构造方法
  • disableBuilder：打开/关闭构造器，如果关闭，则只使用常规的 getters/setters
• 默认值：
  • buildMethod：build
  • disableBuilder：true
• 分别对应的编译参数：
  • -Amapstruct.plus.builder.buildMethod
  • -Amapstruct.plus.builder.disableBuilder

adapterPackage

since 1.2.3

• 说明：ConvertAdapterClass 和 MapConvertMapperAdapter 的包名
• 类型：String
• 默认值：io.github.linpeilie
• 对应编译参数：-Amapstruct.plus.adapterPackage

adapterClassName

since 1.2.3

• 说明：ConvertAdapterClass 类名
• 类型：String
• 默认值：ConvertMapperAdapter
• 对应编译参数：-Amapstruct.plus.adapterClassName

mapAdapterClassName

since 1.2.3

• 说明：MapConvertMapperAdapter 类名
• 类型：String
• 默认值：MapConvertMapperAdapter
• 对应编译参数：-Amapstruct.plus.mapAdapterClassName