JQuick-Excel 首次导入从 Sheet1 表头获得 JQuickRowtags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具简介我是 JQuick-Excel 的作者。本文聚焦第一次导入严格采用测试资源中的 Sheet1、学号、姓名、性别、年龄、出生日期字段以及性别和日期转换规则将上传或资源文件读取为 List。前言导入的入口不是 Java 字段而是用户提交文件中的工作表与表头。最容易发生的错误是把导出映射方向复制到导入规则或把文件名误写进 SHEET。为了让读者能独立验证我把输入文件约束、资源路径、字典方向和返回值都明确写出准备好相同表头之后再接入自己的保存逻辑。环境与依赖我以 Java 8 或更高版本作为运行基线本文固定使用 Maven 坐标io.github.paohaijiao:jquick-excel:3.6.0。仓库 POM 的项目版本为 3.6.0并声明 Apache POI 的poi与poi-ooxml依赖因此可读写 xls 与 xlsx 工作簿。把下面依赖写入业务工程的 pom.xml再把 XML 服务定义放到src/main/resources/jquick-excel.xml。运行时由JQuickXmlFactory按资源名从 classpath 加载该文件仅放在工程根目录不会参与应用资源加载。dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-excel/artifactIdversion3.6.0/version/dependency?xml version1.0 encodingUTF-8?!DOCTYPEexcelsPUBLIC-//PAOHAIJIAO//DTD API EXCEL 1.0//ENclasspath:paohaijiao/dtd/Jquick-excel.dtdexcelsnamespacecom.github.paohaijiao.xml.service.JQuickExcelExportServiceexcelnameimportExcelreturnClassjava.util.List![CDATA[ IMPORT WITH HEADERtrue, SHEETSheet1, MAPPING{学号:no,姓名:name,性别:sex,年龄:age,出生日期:birthday}, TRANSFORM{sex:trans(${dict},${sex}),birthday:dateFormat(${birthday},yyyy-MM-dd)} ]]/excel/excels代码示例服务接口是 XML 规则对 Java 暴露的类型化契约。namespace必须等于接口的全限定名excel name必须等于方法名。测试资源使用带Param的 field、value 参数本文保留这个实际契约不臆造没有在仓库中出现的代理调用形式。packagecom.github.paohaijiao.xml.service;importcom.github.paohaijiao.statement.JQuickRow;importcom.github.paohaijiao.xml.param.Param;importjava.util.List;publicinterfaceJQuickExcelExportService{voidexportExcel(Param(field)Stringfield,Param(value)Stringvalue);ListJQuickRowimportExcel(Param(field)Stringfield,Param(value)Stringvalue);}try(InputStreaminFirstImport.class.getClassLoader().getResourceAsStream(templates/student.xlsx)){MapString,ObjectsexnewHashMap();sex.put(男,1);sex.put(女,2);JContextcontextnewJContext();context.put(dict,sex);JQuickParseHandlerparsernewJQuickExcelImportXmlParseFactory(context,in);JQuickFactoryfactorynewJQuickXmlFactory(parser,jquick-excel.xml);ListJQuickRowrowsfactory.createApi(JQuickExcelExportService.class).importExcel(field,value);System.out.println(rows.size());}原理说明导入解析器接收 JContext 和 InputStream代理调用 importExcel 后按 IMPORT WITH 选择 Sheet1。HEADERtrue 告诉框架首行是表头MAPPING 用中文表头定位列并写入 no、name、sex、age、birthday 字段TRANSFORM 随后利用上下文进行值转换。最终返回 List业务层可在此基础上做领域校验、批量保存和错误聚合。注意事项资源读取结果可能为 null因此真实业务应在创建解析器前确保上传文件或 classpath 资源存在。测试代码的导入字典方向是男到1、女到2不能沿用导出方向。Sheet 名、表头全角半角空格、隐藏换行都可能导致映射失败与其在代码中猜列序不如明确模板并让用户下载标准模板。大文件不要在后续业务层无节制保留所有转换结果。总结导入的边界应停在结构化的JQuickRow模板解析负责把表头和值带进系统必填、权限、重复数据和持久化规则仍由业务层决定。这个分层能避免把不可靠的用户输入直接扩散到后续流程。上线前我会刻意准备表头错字、Sheet 名不符、空行、未知字典值和日期异常的样本。能清楚定位这些常见问题导入入口才算具备交付条件。