spring-boot-starter-converter 文档

spring-boot-starter-converter 是一款为简化DO、BO、DTO等Bean之间转换过程的半自动化框架.

版本支持 | Support Version

• All version - only support for Java 8+,Spring Boot

优点 | Advantages

• 降低耦合：所有转换方法由转换器上下文管理，改变方法签名或者位置等不需要同步更新调用代码；
• 转换时无需记住转换方法名称：直接使用如BeanConverter.convert(source,target.class)这样的方式转换，无需关心转换方法的名称；
• 自动完成列表类型转换：不必手动创建列表类型转换方法，converter会自动帮你完成，可自行选择是否并行转换；
• 支持非静态方法：支持非静态转换方法，避免手动引入Bean，简化代码；
• 可过滤列表中NULL对象：使用前缀为 nonNull的方法，会过滤掉列表中NULL对象，无需手动过滤；
• 可针对NULL对象抛出异常：使用后缀为 IfNullThrow的方法，当出现转换对象或者转换列表中含有NULL对象时抛出指定异常；
• 去除NULL判断：默认情况下，当转换对象为NULL、转换列表为NULL或为空时，返回NULL或者空列表，无需在转换方法中进行NULL判断；
• 可统一各个转换类名称：针对每个业务单元，其转换类名称可全部统一，如Converter，避免取名的烦恼；

Maven 依赖

<dependency>
    <groupId>com.github.liaochong</groupId>
    <artifactId>spring-boot-starter-converter</artifactId>
    <version>1.1.0</version>
</dependency>

使用条件 | Condition

1. 必须使用注解 com.github.liaochong.converter.annoation.EnableConverter 标明启用框架，否则不会进行相应的初始化工作；
2. 必须使用注解 com.github.liaochong.converter.annoation.Converter 标明转换方法所在的转换类，否则转换方法不会被注册；
3. 转换方法必须为 public 修饰符修饰，否则，不会被注册；
4. 转换方法只能有一个参数入参，多个参数的方法不会被注册；
5. 同一类型的参数、返回类型只能有一个注册方法，如有多个，会在启动阶段抛出异常-NonUniqueConverterException；

示例 | Example

1. 使用注解 com.github.liaochong.converter.annoation.EnableConverter 标明启用converter-starter

@SpringBootApplication
@EnableConverter
public class ExampleWarApplication {

    public static void main(String[] args) {
        SpringApplication.run(ExampleWarApplication.class, args);
    }
}

2. 使用注解 com.github.liaochong.converter.annoation.Converter 标明转换类

@Converter
public class UserConverter{

   public static UserBO convertDO2BO(UserDO user){
          UserBO result = new UserBO();
          result.setName(user.getName());
          return result;
   }
}

3. 使用类 com.github.liaochong.converter.core.BeanConverter 进行转换，参数类别依次为：转换源对象，转换目标类类型

• 单个对象转换

UserDO userDO = new UserDO();
UserBO user = BeanConverter.convert(userDO , UserBO.class);

• 列表对象转换

List<UserDO> list = new ArrayList<>();
UserDO userDO1 = new UserDO();
UserDO userDO2 = new UserDO();
list.add(userDO1);
list.add(userDO2);

List<UserBO> users = BeanConverter.convert(list , UserBO.class);

• 列表对象并行转换

List<UserDO> list = new ArrayList<>();
UserDO userDO1 = new UserDO();
UserDO userDO2 = new UserDO();
list.add(userDO1);
list.add(userDO2);

List<UserBO> users = BeanConverter.parallelConvert(list , UserBO.class);

配置 | Configuration

1. （可选-OPTIONAL）bean.conversion.scan-packages：设置扫描路径，支持多个路径，如 bean.conversion.scan-packages=com.test.core,com.test.biz.dao，以英文“,”分隔，若不设置，默认扫描当前项目classpath；
2. （可选-OPTIONAL）bean.conversion.only-scan-static-method：设置是否只扫描静态方法，如 bean.conversion.only-scan-static-method=true，若不设置，默认为 false；
3. （可选-OPTIONAL）bean.conversion.only-scan-non-static-method：设置是否只扫描非静态方法，如 bean.conversion.only-scan-non-static-method=true，若不设置，默认为 false；
4. （可选-OPTIONAL）bean.conversion.strict-mode：设置是否启用严格模式，如bean.conversion.strict-mode=true，严格模式下，当不存在任何转换方法时项目启动过程抛出异常，否则，当不存在任何转换方法时只会在运行时使用抛出异常，若不设置，默认为 false；

接口 | Interface

异常 | Exception

1. NonUniqueConverterException：非唯一转换方法异常，该异常出现在发现 多个转换方法转换同一类型对象到同一目标对象 的情况；
2. ConverterDisabledException：转换器不可用异常，该异常出现出现的原因是使用了BeanConverter的各个方法，但是未使用注解 com.github.liaochong.converter.annoation.EnableConverter 标明启用converter-starter；
3. NoConverterException：无转换方法异常，该异常出现的原因是使用了BeanConverter的方法，但查找不到对应的转换方法；
4. UnsupportedOperationException：非法操作异常，该异常出现的原因是使用了转换上下文不可手动使用的方法；
5. InvalidConfigurationException：无效配置异常，该异常出现的原因是配置冲突导致的无效，如同时设置 bean.conversion.only-scan-static-method=true 和 bean.conversion.only-scan-non-static-method=true导致无法扫描任何转换器；
6. NullPointerException：空指针异常，该异常出现的原因是输入了不合法的参数，如 convert(UserDO user, null)，目标类类型不可为NULL；
7. ConvertException：调用转换方法过程中发生的异常；