JQuick-Excel 项目定位与适用场景：声明式 Java Excel 的边界
tags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具
简介
我是 JQuick-Excel 的作者。本文从项目定位出发，说明它为何把 Excel 规则写入 XML、Java 调用方应承担什么职责，以及它适合报表、模板下载、批量交换和后台运营场景的原因。
前言
我在 Java 项目中处理 Excel 时，真正难的往往不是打开工作簿，而是表头、字典、日期、统计列和模板样式持续变化。若这些规则与业务查询和文件响应混在 Java 循环里，维护成本会随场景数量增长。JQuick-Excel 的目标是把工作簿规则写成可阅读、可审查的 XML DSL，同时保留 Java 对数据和流程的控制。
环境与依赖
我以 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="exportExcel" returnClass="void"><![CDATA[
EXPORT WITH
SHEET="学生表",
HEADER=true,
MAPPING={"id":"主键","name":"姓名","gender":"性别","age":"年龄","enrollmentDate":"入学时间","className":"班级","ignoreField":"是否忽略"},
FORMULAS={D5:'ABS(D2)'},
STYLE={ROW 1:{fontName:Arial,fontHeightInPoints:12,italic:true,color:yellow,bold:true}},
TRANSFORM={"gender":trans(${dict},${gender}),"age":add(${age},1),"enrollmentDate":dateFormat(${enrollmentDate},'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
List<Map<String, Object>> data = new ArrayList<>();
Map<String, Object> student = new LinkedHashMap<>();
student.put("id", "1001");
student.put("name", "张三");
student.put("gender", "1");
student.put("age", 20);
student.put("enrollmentDate", new Date());
data.add(student);
Map<String, Object> dict = new HashMap<>();
dict.put("1", "女");
JContext context = new JContext();
context.put("dict", dict);
List<JQuickRow> rows = JQuickRow.toRows(JObjectConverter.convert(data));
try (OutputStream out = new FileOutputStream("students.xlsx")) {
JQuickParseHandler parser = new JQuickExcelExportXmlParseFactory(context, rows, out);
JQuickFactory factory = new JQuickXmlFactory(parser, "jquick-excel.xml");
factory.createApi(JQuickExcelExportService.class).exportExcel("field", "value");
}原理说明
定位上，JQuick-Excel 是构建在 Apache POI 能力上的轻量级声明式框架，而不是数据库 ORM 或通用报表平台。EXPORT WITH 描述输出工作表，IMPORT WITH 描述输入结构；JQuickXmlFactory 读取 XML 定义并生成接口代理，具体解析器在调用时获得行数据、上下文和流。这样，Excel 展示规则可以独立演进，应用代码仍以领域对象、权限和事务为中心。
注意事项
我建议在表头稳定、规则可配置、需要多人共同维护模板契约的场景使用它，例如管理后台导出、运营上传、教育或人事台账、对账清单和系统间数据交换。不适合把未知来源、无规范表头的任意文件自动猜测为业务模型。复杂流程应先在服务层完成数据治理和错误处理，再让 DSL 专注 Excel 映射。
总结
我更愿意把 JQuick-Excel 看成一份可评审的数据契约，而不是生成附件的工具。项目启动时先把字段、表头和字典方向说清楚，后面的导入导出才不会在临时需求里失控。
实际落地时，用一份最小样本把 XML、代理调用和打开后的工作簿一起验收。规则稳定后，业务代码就能把注意力放回权限、数据治理和流程本身。