{"record":{"id":"e46775b3a6a234b3","repo":"jeecgboot/JeecgBoot","slug":"excel","errorCode":null,"errorMessage":"导入Excel校验失败 ！","messagePattern":"导入Excel校验失败 ！","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"warning","filePath":"jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/controller/SysDictController.java","lineNumber":673,"sourceCode":"\t * @return\n\t */\n    @RequiresPermissions(\"system:dict:importExcel\")\n\t@RequestMapping(value = \"/importExcel\", method = RequestMethod.POST)\n\tpublic Result<?> importExcel(HttpServletRequest request, HttpServletResponse response) {\n \t\tMultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;\n\t\tMap<String, MultipartFile> fileMap = multipartRequest.getFileMap();\n\t\tfor (Map.Entry<String, MultipartFile> entity : fileMap.entrySet()) {\n            // 获取上传文件对象\n\t\t\tMultipartFile file = entity.getValue();\n\t\t\tImportParams params = new ImportParams();\n\t\t\tparams.setTitleRows(2);\n\t\t\tparams.setHeadRows(2);\n\t\t\tparams.setNeedSave(true);\n\t\t\ttry {\n\t\t\t\t//导入Excel格式校验，看匹配的字段文本概率\n\t\t\t\tBoolean t = ExcelImportCheckUtil.check(file.getInputStream(), SysDictPage.class, params);\n\t\t\t\tif(t!=null && !t){\n\t\t\t\t\tthrow new RuntimeException(\"导入Excel校验失败 ！\");\n\t\t\t\t}\n\t\t\t\tList<SysDictPage> list = ExcelImportUtil.importExcel(file.getInputStream(), SysDictPage.class, params);\n\t\t\t\t// 错误信息\n\t\t\t\tList<String> errorMessage = new ArrayList<>();\n\t\t\t\tint successLines = 0, errorLines = 0;\n\t\t\t\tfor (int i=0;i< list.size();i++) {\n\t\t\t\t\tSysDict po = new SysDict();\n\t\t\t\t\tBeanUtils.copyProperties(list.get(i), po);\n\t\t\t\t\tpo.setDelFlag(CommonConstant.DEL_FLAG_0);\n\t\t\t\t\ttry {\n\t\t\t\t\t\tInteger integer = sysDictService.saveMain(po, list.get(i).getSysDictItemList());\n\t\t\t\t\t\tif(integer>0){\n\t\t\t\t\t\t\tsuccessLines++;\n                        // 代码逻辑说明: [JTC-1168]如果字典项值为空，则字典项忽略导入------------\n\t\t\t\t\t\t}else if(integer == -1){\n                            errorLines++;\n                            errorMessage.add(\"字典名称：\" + po.getDictName() + \"，对应字典列表的字典项值不能为空，忽略导入。\");\n                        }else{","sourceCodeStart":655,"sourceCodeEnd":691,"githubUrl":"https://github.com/jeecgboot/JeecgBoot/blob/96fb33f5ec68516da0b0147da06b2eb0419e063a/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/controller/SysDictController.java#L655-L691","documentation":"During SysDict Excel import, ExcelImportCheckUtil.check computes how well the uploaded workbook's header rows match the SysDictPage fields. When the match probability is too low (returns false), the file is judged not to be a valid SysDict import template and a RuntimeException is thrown, aborting the import before AutoPoi tries to parse it.","triggerScenarios":"Uploading an Excel whose columns do not match SysDictPage fields; uploading an unrelated report; using a template from an older/newer JeecgBoot version whose SysDictPage columns differ; a non-xlsx file renamed to .xlsx.","commonSituations":"User downloaded the wrong template; template version drift after an upgrade; manual edits shifted the two title rows (titleRows=2, headRows=2) out of alignment.","solutions":["Re-download the official SysDict import template from the dict management page and fill only its columns.","Confirm the header layout matches (2 title rows, 2 head rows) and column names align with SysDictPage.","If the file is genuinely a dict template but still rejected, verify the SysDictPage field set matches this build's version."],"exampleFix":"// before: importing an arbitrary workbook\nMultipartFile f = userFile; // wrong template\n// after: validate against the official template before upload, or\n// catch the failure and report the expected columns to the user\ntry {\n    Boolean ok = ExcelImportCheckUtil.check(f.getInputStream(), SysDictPage.class, params);\n    if (ok != null && !ok) return Result.error(\"请使用系统下载的字典导入模板\");\n} catch (Exception ex) { return Result.error(\"模板读取失败: \" + ex.getMessage()); }","handlingStrategy":"validation","validationCode":"// Client/server pre-check: confirm the workbook looks like a SysDict template before importing.\nBoolean ok = ExcelImportCheckUtil.check(file.getInputStream(), SysDictPage.class, params);\nif (ok != null && !ok) {\n    return Result.error(\"请使用系统下载的字典导入模板\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return sysDictController.importExcel(request);\n} catch (RuntimeException e) {\n    if (\"导入Excel校验失败 ！\".equals(e.getMessage())) {\n        return Result.error(\"Excel 模板不匹配, 请下载最新模板后重试\");\n    }\n    throw e;\n}","preventionTips":["Always import from the template downloaded from the same JeecgBoot version.","Lock the header rows (titleRows=2, headRows=2) so users cannot shift them.","Reject non-.xlsx uploads at the controller before reaching the check."],"tags":["excel","import","autopoi","validation"],"backgroundTag":null,"analyzedSha":"96fb33f5ec68516da0b0147da06b2eb0419e063a","analyzedAt":"2026-08-14T00:04:16.786Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}