企业官网建设流程全解析

JQuick-Excel XML DSL 工作流：从服务定义到代理执行

tags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具

简介

我是 JQuick-Excel 的作者。本文只讨论 XML 与 DSL 的工作方式，说明 XML 外壳、CDATA 规则、服务接口、解析器和工厂如何组成一条可执行链路，并给出可从测试资源直接推导的配置形式。

前言

声明式方案的关键不是把 Java 改写成 XML，而是把不同职责放到合适位置。XML 的 excels 元素提供服务 namespace，excel 元素提供可调用操作，CDATA 中的 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 加载该文件；仅放在工程根目录不会参与应用资源加载。

<dependency><groupId>io.github.paohaijiao</groupId><artifactId>jquick-excel</artifactId><version>3.6.0</version></dependency>```xml<?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="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><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);}

JQuickParseHandlerparser=newJQuickExcelExportXmlParseFactory(context,rows,outputStream);JQuickFactoryfactory=newJQuickXmlFactory(parser,"jquick-excel.xml");JQuickExcelExportServiceservice=factory.createApi(JQuickExcelExportService.class);service.exportExcel("field","value");

原理说明

调用发生时，JQuickXmlFactory 按资源名读取 XML，并以接口类型创建代理。调用代理方法后，代理根据方法名定位 excel 定义；导出解析器读取行数据和输出流，导入解析器读取上下文和输入流；DSL 被解析为相应模型，再执行映射、转换、样式或读取。MAPPING、TRANSFORM、FORMULAS、STYLE 各自是规则部分，不能用 Java 方法名或文件路径替代。

注意事项

XML 采用 CDATA 是为了让 DSL 中的花括号、引号和表达式保持原样。不要省略 DTD，也不要将 namespace 写成示例接口之外的包名后仍使用原接口创建代理。一个 XML 可以声明多个 excel 操作，但每个 name 必须唯一且与接口方法严格对应。修改配置后，应确认构建资源复制过程没有遗漏 jquick-excel.xml。

总结

XML DSL 的价值是让工作簿规则进入可单独评审的位置。资源路径、namespace、方法名和 CDATA 都是这条链路的一部分，不能只检查 DSL 里面的几行参数。

我会用最小样本先验证规则，再接入真实业务数据；这样出现偏差时，能判断是模板配置、输入文件还是业务流程的问题。