高效导入功能设计规范指南

导入功能设计规范

一、导入工程流程

导入工程流程一般如下：

1. 下载模板
2. 上传文件解析
3. 下载解析报告 或 确认导入

二、接口规范

1. 下载模板

• 接口规范：GET 请求，无需参数

/**
 * 下载模板
 *
 * @param response
 */
@GetMapping("template")
public void template(HttpServletResponse response) {
    programGradService.template(response);
}

• 下载模板一般是从 MinIO 上读取已经上传的模板进行导入，也可以通过代码生成模板，如下：

public void download(String examBatchId, HttpServletResponse response) {
    // 获取表头
    List<String> headerRow = this.getHeaderList(examBatchId);

    // 生成文件
    try {
        String fileName = leExamBatch.getName() + "导入模板.xls";
        response.setContentType("application/x-msdownload");
        response.setHeader("Content-Disposition", "attachment; filename="
                + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()));
        OutputStream out = response.getOutputStream();
        List<List<String>> rows = CollUtil.newArrayList(Collections.singleton(headerRow));
        ExcelWriter writer = ExcelUtil.getWriter();
        writer.write(rows);
        writer.flush(out);
        writer.close();
    } catch (Exception e) {
        throw new UniException("下载失败");
    }
}

2. 解析文件

• 接口规范：POST 请求，表单形式传参
• 入参为文件，返回参数为对象，在工具类里面已经定义好统一返回类 AnalyzeResultVO，属性包含表头、所有数据、解析成功的数据、解析失败的数据、成功的条数、失败的条数。

/**
 * 解析文件
 *
 * @param file
 */
@PostMapping("analysis")
public Response<AnalyzeResultVO> analysis(@RequestParam("file") MultipartFile file) {
    return Response.ok(programGradService.analysis(file));
}

解析返回对象 AnalyzeResultVO

public class AnalyzeResultVO<T> {

    /**
     * 表头
     */
    private List<String> headerList;

    /**
     * 解析总的数据，用于前端展示
     */
    private List<List<String>> dataList;

    /**
     * 解析成功的数据，用于后端导入
     */
    private List<T> successList;

    /**
     * 解析失败的数据，用于后端下载解析报告
     */
    private List<T> errorList;

    /**
     * 成功条数
     */
    private Integer successNums;

    /**
     * 失败条数
     */
    private Integer errorNums;
}

• 后端解析时，可以使用工具类 TableUtils 直接获取表头，并将数据解析成 List<List<String>>。需要在解析对象属性上添加注解 @TableHeader，再通过工具类方法直接获取数据。

注意：为了规范，解析对象第一个属性为状态，最后一个属性为解析失败的原因。后续转换为二维数组时按属性顺序转换，方便前端展示状态和原因。

解析数据对象示例

@Data
@Accessors(chain = true)
@NoArgsConstructor
@AllArgsConstructor
public class AnalyzeDownGradeImportVO {

    /**
     * 解析结果
     */
    @TableHeader(value = "状态")
    private String status;

    /* 具体解析的列属性 */

    /**
     * 申请说明
     */
    @TableHeader(value = "申请说明")
    @Excel(name = "申请说明")
    private String reason;

    /**
     * 解析原因
     */
    @TableHeader(value = "原因")
    private String analyzeReason;
}

具体解析方法

// 解析数据，使用 easyPOI 解析；不存在复杂表头时使用，否则使用 POI 进行解析
List<PunishImportVO> punishImports = EasyPoiUtil.importExcel(file, 0, 1, PunishImportVO.class, new ArrayList<>(0));

public AnalyzePunishVO analysePunishImportErrorInfo(List<PunishImportVO> punishImportDTOList) {
    if (CollectionUtils.isEmpty(punishImportDTOList)) {
        return new AnalyzePunishVO();
    }

    List<PunishImportVO> successImportVoS = new ArrayList<>(10);
    List<PunishImportVO> errorImportVoS = new ArrayList<>(10);

    Integer failureNum = 0;
    Integer successNum = 0;

    for (PunishImportVO punish : punishImportDTOList) {
        // 具体判断数据是否成功/失败
        if (StringUtils.isBlank(punish.getLifeCycle())) {
            errorImportVoS.add(punish
                .setStatus("失败")
                .setReason("失败的原因"));
            failureNum++;
        }

        // 成功的数据
        successNum++;
        successImportVoS.add(punish.setStatus("成功"));
    }

    return new AnalyzeResultVO<PunishImportVO>()
        .setSuccessList(successImportVoS)
        .setErrorNums(failureNum)
        .setSuccessNums(successNum)
        .setErrorList(errorImportVoS);
}

工具类转换

public <T> AnalyzeCommonApplyVO analyzeCommonApplyResponse(List<T> analyzeList, Class<T> clazz) {
    // 将对象转换成 string
    List<List<String>> tableData = TableUtils.getTableData(analyzeList, clazz);

    // 获取表头
    List<String> header = TableUtils.getTableHeader(clazz);

    return new AnalyzeResultVO<PunishImportVO>()
        .setHeaderList(header)
        .setDataList(tableData);
}

3. 下载解析报告

• 接口规范：POST 方式，JSON 格式传参
• 前端只需传失败的数据到后端下载解析报告

/**
 * 下载解析报告
 *
 * @param dto
 */
@PostMapping("analysis-report")
public void downloadAnalysis(@RequestBody ProgramGradDTO dto, HttpServletResponse response) {
    programGradService.downloadAnalysis(dto, response);
}

4. 导入

• 接口规范：POST 方式，JSON 格式传参
• 前端只需传成功的数据到后端，后端需把成功的数据再进行一次解析，然后再进行导入

/**
 * 导入
 *
 * @param dto
 */
@PostMapping("import")
public Response importProgramGrad(@RequestBody ProgramGradDTO dto) {
    programGradService.importProgramGrad(dto);
    return Response.ok();
}