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 加载该文件；仅放在工程根目录不会参与应用资源加载。

xml 复制代码

<dependency>
  <groupId>io.github.paohaijiao</groupId>
  <artifactId>jquick-excel</artifactId>
  <version>3.6.0</version>
</dependency>

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE excels PUBLIC "-//PAOHAIJIAO//DTD API EXCEL 1.0//EN"
        "classpath:paohaijiao/dtd/Jquick-excel.dtd">
<excels namespace="com.github.paohaijiao.xml.service.JQuickExcelExportService">
    <excel name="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 参数，本文保留这个实际契约，不臆造没有在仓库中出现的代理调用形式。

java 复制代码

package com.github.paohaijiao.xml.service;

import com.github.paohaijiao.statement.JQuickRow;
import com.github.paohaijiao.xml.param.Param;
import java.util.List;

public interface JQuickExcelExportService {
    void exportExcel(@Param("field") String field, @Param("value") String value);
    List<JQuickRow> importExcel(@Param("field") String field, @Param("value") String value);
}

java 复制代码

try (InputStream in = FirstImport.class.getClassLoader()
        .getResourceAsStream("templates/student.xlsx")) {
    Map<String, Object> sex = new HashMap<>();
    sex.put("男", "1");
    sex.put("女", "2");
    JContext context = new JContext();
    context.put("dict", sex);
    JQuickParseHandler parser = new JQuickExcelImportXmlParseFactory(context, in);
    JQuickFactory factory = new JQuickXmlFactory(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 名不符、空行、未知字典值和日期异常的样本。能清楚定位这些常见问题，导入入口才算具备交付条件。