JQuick-Excel 多字段 TRANSFORM：让当前行字段、JContext 与展示列各归其位

JQuick-Excel 多字段 TRANSFORM让当前行字段、JContext 与展示列各归其位tags: #Java #JQuickExcel #Excel导出 #TRANSFORM #SPI简介Excel 导出中的字段转换难点通常不在于把一个字符串改成大写而在于一张报表同时有当前行字段、公共字典、日期值和派生展示列。JQuick-Excel 的TRANSFORM为这类需求提供了声明式位置${field}读取当前行字段${key}也可以读取JContext中的值函数接收完成求值后的参数并返回转换结果。本文只依据 README-CN 说明这一边界使用内置toUpper、dateFormat、trans并以fullName说明多字段派生列的组织方式。这里的“多字段”有两层含义。第一层是一个函数可以引用同一行的多个字段例如把名和姓组合为显示名称。第二层是同一份TRANSFORM可同时处理文本、日期和字典编码。它并不意味着可以在 XML 中任意编排业务流程。报表 XML 适合描述字段到单元格之间稳定、可验证的转换查库、远程调用、权限判定和批处理策略仍应由应用层处理。前言真实报表往往不是把 Java 对象原样写进工作簿。学生名单可能需要将姓名统一大写把性别编码翻译为文案把入学日期按固定格式展示并额外输出一个“显示名称”列。若所有这些规则都分散在 Java 循环里读 XML 的人无法知道列值如何得到若把数据准备也塞进表达式又会使逐行导出的行为不可预测。我会先把参与数据分成三类。当前行字段是每条记录独有的输入如firstName、lastName、gender与enrollmentDate。JContext是一次解析过程中共享的外部数据如编码字典。派生字段是报表需要而源对象未必原生具备的输出如displayName。这种划分不是额外框架规则而是组织报表的实践读者能清楚判断一个值来自当前行、来自上下文还是由函数计算得到。随后再确定列责任。MAPPING定义源字段与表头的映射TRANSFORM定义写出前的字段转换FORMAT管理最终 Excel 单元格显示格式。README-CN 明确指出FORMAT独立负责转换后的 Excel 单元格显示。因而日期规则要区分“值如何被格式化”与“单元格如何显示”前者是dateFormat后者是FORMAT。将两者混为一谈是排查日期问题时最常见的误区。多字段规则还应保持可追踪性。一个派生列的 key 应明确出现在MAPPING表达式中的${...}应能在当前行或JContext中找到来源函数名应来自已确认的函数集合。这样字段改名、列重排和字典调整时修改范围可控也能为每个字段准备清晰的验收样本。环境与依赖README-CN 给出的核心 Maven 坐标是io.github.paohaijiao:jquick-excel:3.6.0。JQuick-Excel 要求 Java 8 或更高版本支持xls与xlsx。本篇基础示例只依赖核心库和 README-CN 已确认的内置函数不把未确认的表达式函数当作前提。XML 定义应位于类路径中并由 XML 工厂结合导出解析器创建服务代理。dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-excel/artifactIdversion3.6.0/version/dependencyJava 侧负责准备行数据、输出流以及本次导出共享的上下文。XML 侧负责EXPORT WITH、MAPPING、TRANSFORM与FORMAT。DSL 的关键字、花括号、逗号、字段名和表达式分隔符都属于配置契约修改时不能依靠“看起来相近”的写法替换。特别是${dict}与${gender}的含义不同前者应指向上下文字典后者应指向当前行的编码字段。如果业务确实需要fullName这样的跨报表函数则需要按 SPI 提供者方式实现并在运行时类路径中提供它。本文在 XML 中用fullName(${firstName},${lastName})展示多字段引用的形态其 provider 的具体实现与服务文件将在自定义 SPI 主题中单独讨论。内置函数部分只使用toUpper、dateFormat与trans。代码示例下面的导出规则有六列原始名、原始姓、派生显示名称、性别、年龄与入学日期。displayName的输出位置由MAPPING明确声明lastName使用内置toUpper性别通过JContext中的dict使用内置trans翻译日期使用内置dateFormat并保留FORMAT作为单元格显示规则。示例不假设转换规则之间存在未文档化的依赖或执行顺序。excelnameexportExcelreturnClassvoid![CDATA[ EXPORT WITH SHEETStudents, HEADERtrue, MAPPING{ firstName:First Name, lastName:Last Name, displayName:Display Name, gender:Gender, age:Age, enrollmentDate:Enrollment Date }, TRANSFORM{ displayName:fullName(${firstName},${lastName}), lastName:toUpper(${lastName}), gender:trans(${dict},${gender}), enrollmentDate:dateFormat(${enrollmentDate},yyyy-MM-dd) }, FORMAT{enrollmentDate:yyyy-MM-dd} ]]/excelREADME-CN 的导入示例展示了JContext的构造与put用法本文只以它说明${dict}所代表的上下文字典语义不推导 README 未展示的导出上下文注入 API。导出数据仍可按JObjectConverter和JQuickRow的已确认路径准备。ListJQuickRowrowsJQuickRow.toRows(JObjectConverter.convert(people));try(OutputStreamoutputnewFileOutputStream(students.xlsx)){JQuickParseHandlerparsernewJQuickExcelExportXmlParseFactory(rows,output);JQuickExcelExportServiceservicenewJQuickXmlFactory(parser,jquick-excel.xml).createApi(JQuickExcelExportService.class);service.exportExcel(field,value);}验收时不要只打开文件看一条正常数据。至少应准备名和姓都存在的记录用于检查displayName不同大小写的姓用于检查toUpper字典中存在的性别编码用于检查trans日期值用于检查dateFormat与FORMAT以及缺失字段、未知编码和异常日期等边界数据。对每种样本同时检查列位置、单元格值和显示形式才能区分映射错误、上下文错误与格式错误。原理说明README-CN 给出的转换模型足以解释这份规则当前行字段或JContext值经${...}取值后进入TRANSFORM表达式求值后的参数交给内置求值器或 SPI provider函数返回转换结果最后FORMAT控制 Excel 显示。这里最重要的事实是函数接收的是参数列表而不是 XML 文本因此函数的输入语义由字段值和上下文值决定函数名和参数顺序必须稳定。当前行字段随记录变化。每处理一行${firstName}、${lastName}、${gender}和${enrollmentDate}应对应这一行的数据。JContext中的dict则是共享数据适合字典类转换。将公共字典重复放入每个业务对象没有必要将当前行数据伪装成共享上下文也会让来源含混。把两者分开后出现空值时可以先判断源字段是否缺失再判断上下文是否准备完成。派生字段不是特殊类型。displayName的意义只是一个被映射到输出列的字段其值由fullName返回。关键不在于源对象中是否预先存在该属性而在于报表规则是否为它声明了明确列位和明确输入。对于只想标准化已有字段的情况例如将lastName转大写直接以原字段作为TRANSFORMkey 更直观。对于要新增展示列的情况则让派生字段同时出现在MAPPING与TRANSFORM中。日期的两个层次需要单独验证。dateFormat(${enrollmentDate},yyyy-MM-dd)是内置函数调用FORMAT{enrollmentDate:yyyy-MM-dd}是单元格显示控制。README-CN 已明确二者职责独立。出现日期异常时先确认函数输入和返回是否符合预期再确认工作簿中单元格显示格式避免仅修改一处而掩盖另一处的问题。多字段转换的可维护性来自小而明确的规则。toUpper只处理文本大写dateFormat只处理日期格式trans只做上下文字典映射fullName只组合两个输入。不要在逐行函数中加入数据库查询、网络请求或依赖共享可变状态的逻辑。此类行为既不属于 README-CN 所描述的转换契约也会使性能、异常处理和结果一致性难以控制。导入和导出都可以使用TRANSFORM但业务方向并不相同。导出通常把编码转换成给人看的文案导入可能需要反向处理。不能因为两侧语法相同就不加验证地复制同一份字典规则。每个方向都应有独立的输入样本和预期输出尤其是日期、编码和空值数据。注意事项第一派生字段要在MAPPING中有明确输出列。只写TRANSFORM{displayName:...}而没有对应列会使报表设计失去清晰的落点。字段名调整时应同步检查 MAPPING key、${field}引用、TRANSFORM key 与 FORMAT key。第二创建解析器前准备JContext。${dict}的键名必须与context.put(dict, gender)相同。字典应由应用层准备为本次导出稳定可用的数据未知编码的业务展示结果应通过样本显式验证而不是假定它会自动得到某个文案。第三只调用确认存在的函数。核心内置函数以 README-CN 明示的toUpper、dateFormat、trans为准。fullName是自定义 SPI 示例只有 provider 和服务资源实际在类路径中时才可调用。不要根据其他 Java 工具库的习惯猜测函数名、嵌套能力或自动类型转换。第四不要把FORMAT当成业务转换也不要把业务转换当成 Excel 公式。FORMAT管显示TRANSFORM管导出前的值转换FORMULAS是另一项工作簿公式功能。名称相似不代表执行时机和结果类型相同。第五转换路径按行运行。复杂逻辑应在导出前完成函数保持无状态、确定且低开销。对于大数据导出数据准备、字典构建和批次控制更应该放在应用层避免每行重复做昂贵工作。第六保留可读性。一个字段需要多个难以解释的条件时与其把 XML 堆成不可审查的表达式不如先明确业务口径并将跨报表复用的稳定逻辑实现为命名清晰的 SPI provider。XML 应让维护者看懂列从哪里来、经过什么转换、最终怎样展示。规则拆分与验证多字段模板的审查重点应是每个输出字段的依赖范围。以displayName为例它依赖当前行的firstName和lastName性别列还依赖共享的${dict}日期列则依赖当前行日期值和格式参数。将依赖写成这样的清单不会改变 DSL 行为却可以避免维护者把上下文值、当前行值与表头名称混为同一类输入。派生字段的验收还要确认它不会取代原始字段。示例中displayName是单独映射的列firstName、lastName仍各有输出位置而lastName的toUpper是对已有输出字段的值转换。这两种写法分别表达“新增展示字段”和“修改指定字段的写出值”。若需求只要求其中一种应避免同时配置两种以免工作簿出现重复却含义不清的列。同一份TRANSFORM中的规则不应建立在未确认的配置项先后顺序上。每一项应只依赖当前行可获得的字段、JContext中已准备的值和函数显式参数。对于需要把一个转换结果再作为另一个规则输入的需求不能从本文所依据的事实推导其执行顺序应先在应用层准备明确字段或以项目实际版本的行为验证后再采用。这样不会将隐含顺序变成报表契约。日期字段应从值和显示两个角度验收。dateFormat是内置转换函数FORMAT是单元格显示配置样本检查应记录转换后的字段结果以及在 Excel 中看到的显示文本。若业务还要对导出的日期做后续计算则需要由项目根据实际类型和目标模板验证可计算性不能仅因显示为yyyy-MM-dd就推断其数据语义。字典转换也应单独覆盖方向和范围。trans(${dict},${gender})表达式的字典来自JContext当前编码来自处理中的行当同一报表导出多批数据时应用层应确保为该批次准备的字典符合业务范围。TRANSFORM只针对当前行求值不负责识别某个编码是否在其他行出现过也不负责决定字典的加载来源。对于 SPI 形式的fullName模板的可移植条件是 provider 实际可用。它的存在不能仅由 XML 中的函数名证明。内置函数与自定义函数在规则中可以并列出现但验收应将它们分开内置toUpper、dateFormat、trans按核心已确认能力测试fullName则按项目提供的 SPI provider 与运行时类路径测试。这样函数缺失时能准确定位为扩展部署问题而不会误判字段映射。总结多字段TRANSFORM的关键是输入来源清楚当前行字段提供记录级数据JContext承担共享字典函数只生成目标列的值。姓名组合、状态翻译和文本标准化可以写在 DSL 中但原始字段仍应保留清晰语义避免展示值反过来参与后续计算。验证时同时覆盖正常记录、缺失字段和字典未命中的情况并核对转换后的值是否仍符合列的使用方式。一次性展示规则留在内置能力范围内确实需要跨报表复用时再将逻辑放入 SPI provider避免 XML 和业务准备层重复承担同一段转换。