JQuick-Excel 首次导入：从 Sheet1 表头获得 JQuickRow
tags: #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 加载该文件；仅放在工程根目录不会参与应用资源加载。
<dependency><groupId>io.github.paohaijiao</groupId><artifactId>jquick-excel</artifactId><version>3.6.0</version></dependency><?xml version="1.0" encoding="UTF-8"?><!DOCTYPEexcelsPUBLIC"-//PAOHAIJIAO//DTD API EXCEL 1.0//EN""classpath:paohaijiao/dtd/Jquick-excel.dtd"><excelsnamespace="com.github.paohaijiao.xml.service.JQuickExcelExportService"><excelname="importExcel"returnClass="java.util.List"><![CDATA[ IMPORT WITH HEADER=true, SHEET='Sheet1', 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);List<JQuickRow>importExcel(@Param("field")Stringfield,@Param("value")Stringvalue);}try(InputStreamin=FirstImport.class.getClassLoader().getResourceAsStream("templates/student.xlsx")){Map<String,Object>sex=newHashMap<>();sex.put("男","1");sex.put("女","2");JContextcontext=newJContext();context.put("dict",sex);JQuickParseHandlerparser=newJQuickExcelImportXmlParseFactory(context,in);JQuickFactoryfactory=newJQuickXmlFactory(parser,"jquick-excel.xml");List<JQuickRow>rows=factory.createApi(JQuickExcelExportService.class).importExcel("field","value");System.out.println(rows.size());}原理说明
导入解析器接收 JContext 和 InputStream，代理调用 importExcel 后按 IMPORT WITH 选择 Sheet1。HEADER=true 告诉框架首行是表头，MAPPING 用中文表头定位列并写入 no、name、sex、age、birthday 字段，TRANSFORM 随后利用上下文进行值转换。最终返回 List，业务层可在此基础上做领域校验、批量保存和错误聚合。
注意事项
资源读取结果可能为 null，因此真实业务应在创建解析器前确保上传文件或 classpath 资源存在。测试代码的导入字典方向是男到1、女到2，不能沿用导出方向。Sheet 名、表头全角半角空格、隐藏换行都可能导致映射失败；与其在代码中猜列序，不如明确模板并让用户下载标准模板。大文件不要在后续业务层无节制保留所有转换结果。
总结
导入的边界应停在结构化的JQuickRow：模板解析负责把表头和值带进系统，必填、权限、重复数据和持久化规则仍由业务层决定。这个分层能避免把不可靠的用户输入直接扩散到后续流程。
上线前我会刻意准备表头错字、Sheet 名不符、空行、未知字典值和日期异常的样本。能清楚定位这些常见问题，导入入口才算具备交付条件。
