• 通用导入客户端


    一、简介

    1.1 概述

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

    1.2 组件坐标

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

    1.3 功能特性

    1.4 配置参数

    # 服务启动是否执行表初始化脚本,默认值false
    hzero.import.initTable
    
    # 是否开启数据导入到正式表的事务控制,默认值true
    hzero.import.transactionControl
    
    # 数据操作的批次量,默认值3000
    hzero.import.batchSize
    

    二、使用说明

    2.1 添加依赖

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

    2.2 数据导入流程

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

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

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

    同步导入与异步导入

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

    通用导入API

    2.3 后台开发指导

    2.3.1 建表

    在当前服务的数据库中新建himp_datahimp_importhimp_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) {
                // 记录错误信息
                getContext().addErrorMsg("这条数据有错");
                // 失败
                return false;
            }
            repository.insertSelective(user);
            // 回写信息
            getContext().addBackInfo(String.valueOf(user.getUserId()));
            // 成功
            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,即不分批,一次获取所有数据

    **注意:**若相同模板编码同时存在IDoImportServiceIBatchImportService的不同实现,只会执行IBatchImportServicedoImport方法

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

    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还是抛异常自己决定
            getContext().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]