通用导入客户端

一、简介

1.1 概述

通用导入客户端提供数据的通用导入功能，集成数据导入与数据校验接口

1.2 组件坐标

<dependency>
    <groupId>org.hzero.boot</groupId>
    <artifactId>hzero-boot-import</artifactId>
    <version>${hzero.boot.version}</version>
</dependency>

1.3 功能特性

配合导入服务使用

二、使用说明

2.1 添加依赖

服务需要添加hzero-boot-import依赖，启动服务后，可以在swagger-ui中看到如下API，则说明添加成功通用导入API

2.2 数据导入流程

① 调用上述从excel导入临时表接口，将excel数导入临时表，会返回一个批号

② 调用验证临时表数据接口，验证excel数据

③ 调用从临时表导入正式表接口，将上一步通过验证的数据导入正式表中

补充说明：从临时表导入正式表接口只会导入校验通过的数据，可以通过查询已上传数据接口查询校验失败的数据，调用更新接口修改错误数据，再重复②③步

同步导入与异步导入

上述为异步导入相关接口，适用于数据量较大的导入场景。本客户端同时提供了同步导入的方法，仅适用于小数据量的导入

通用导入API

2.3 后台开发指导

2.3.1 建表

在当前服务的数据库中新建himp_data、himp_import、himp_local_template表，用于存储临时数据。
本客户端自带建表脚本开启配置即可在服务启动时自动创建相关表

hzero:
  import:
    init-table: true

2.3.2 自定义导入逻辑

开发人员必须自定义导入逻辑，实现接口org.hzero.boot.imported.app.service.IDoImportService，重写doImport方法。
类加注解@org.hzero.boot.imported.infra.validator.annotation.ImportService,声明模板编码

@ImportService(templateCode = "TEST")
public class ImportServiceImpl implements IDoImportService {

    @Autowired
    private ObjectMapper objectMapper;
    @Autowired
    private DemoRepository repository;

    @Override
    public Boolean doImport(String data) {
        User user;
        try {
            user = objectMapper.readValue(data, User.class);
        } catch (IOException e) {
            // 失败
            return false;
        }
        repository.insertSelective(user);
        // 成功
        return true;
    }
}

调用从临时表导入正式表接口会遍历数据执行此方法。

若方法需要获取自定义参数，需要继承org.hzero.boot.imported.app.service.ImportHandler

@ImportService(templateCode = "TEST")
public class ImportServiceImpl extends ImportHandler {

    @Autowired
    private ObjectMapper objectMapper;
    @Autowired
    private DemoRepository repository;

    @Override
    public Boolean doImport(String data) {
        // 获取自定义参数
        Map<String, Object> args = getArgs();
        User user;
        try {
            user = objectMapper.readValue(data, User.class);
        } catch (IOException e) {
            // 失败
            return false;
        }
        repository.insertSelective(user);
        // 成功
        return true;
    }
}

上述为数据逐条导入，数据批量导入可实现org.hzero.boot.imported.app.service.IBatchImportService，重写doImport方法。
类加注解@org.hzero.boot.imported.infra.validator.annotation.ImportService,声明模板编码

@ImportService(templateCode = "TEST")
public class ImportServiceImpl implements IBatchImportService {

    @Override
    public Boolean doImport(List<String> data) {
        // do import
        System.out.println(data);
        return true;
    }

    @Override
    public int getSize(){
        return 500;
    }
}

若方法需要获取自定义参数，需要继承org.hzero.boot.imported.app.service.BatchImportHandler

@ImportService(templateCode = "TEST")
public class ImportServiceImpl extends BatchImportHandler {

    @Override
    public Boolean doImport(String data) {
        // 获取自定义参数
        Map<String, Object> args = getArgs();
        // do import
        System.out.println(data);
        return true;
    }

    @Override
    public int getSize(){
        return 500;
    }
}

批量导入时，每次读取的数据量由getSize()方法控制，默认返回0，即不分批，一次获取所有数据

**注意:**若相同模板编码同时存在IDoImportService和IBatchImportService的不同实现，只会执行IBatchImportService的doImport方法

导入事务控制: 数据导入自动进行事务控制，无需自行控制事务。导入成功结束，事务统一提交。捕获到任何异常，事务统一回滚。

2.3.3 自定义校验逻辑

开发人员如果需要自定义校验逻辑，比如数据的唯一性校验等，可以自定义类继承org.hzero.boot.imported.app.service.ValidatorHandler，重写validate方法。类需要加注解@org.hzero.boot.imported.infra.validator.annotation.ImportValidators，声明模板编码，可以一次声明多个模板编码，都会走当前实现类

@ImportValidators({
    @ImportValidator(templateCode = "TEST")
    })
public class ImportValidatorTest extends ValidatorHandler {

    @Override
    public boolean validate(String data) {
        // 获取自定义参数
        Map args = getArgs();
        // 添加错误信息，抛异常会导致后续数据不再执行校验逻辑，使用addErrorMsg还是抛异常自己决定
        context.addErrorMsg("这条数据有错");
        // do something 
        return true;
    }
}

调用验证临时表数据接口会遍历数据执行此方法，需要注意的是，自定义校验不会受到导入服务中定义的数据验证字段的影响

三、版本更新日志

版本 0.7.0.RELEASE [2018-11-29]

数据导入基础功能

版本 0.10.0.RELEASE [2019-06-23]

添加同步导入功能
添加导入过程自定义参数

版本 0.10.0.RELEASE [2019-06-23]

添加同步导入功能
添加导入过程自定义参数

版本 1.0.0.RELEASE [2019-09-06]

添加导入事务控制
添加CSV文件导入支持
替换自定义校验器