做企业级开发的同学，几乎都躲不开一个需求：动态生成Word文档。合同要根据客户信息自动填充、报表要按月份批量导出、检测报告要把一堆数据和图表塞进固定格式的模板里、简历系统要一键生成规范的Word 简历……这类需求看着不起眼，可真动手做起来，坑一个接一个。如果直接用 Apache POI 硬写，你得跟 XWPFDocument、XWPFParagraph、XWPFRun 这些底层 API 死磕。光是把一段带格式的文字写进去就要几十行代码，更别提插入表格、图片、列表了，代码又臭又长还极难维护。业务方稍微改一下文档格式，你的 Java 代码就得跟着大改一遍，这种强耦合简直是噩梦。poi-tl就是为了解决这个痛点而生的。它的名字是 poi template language 的缩写，本质是一个基于 Apache POI 的 Word 模板引擎。核心理念很简单：用一个 Word 文档当模板，在里面用特定语法写好占位标签，程序运行时把数据往里一填，最终文档就出来了。整个过程你几乎不用碰 POI 的底层 API，模板长什么样、数据怎么排布，都交给设计精良的模板和渲染引擎去搞定。今天这篇文章，我们把 poi-tl 从底层架构到核心特性、从集成方案到实战场景彻底讲透。
一、poi-tl到底解决了什么问题
在深入架构之前，先把 poi-tl 的定位说清楚，否则容易和其他文档方案搞混。市面上生成 Word 的方案大致分三类：第一类是纯代码生成。直接用 Apache POI 一行行拼文档，灵活性最高但开发成本极其昂贵。文档格式和代码强耦合，改格式就得改代码，完全不适合频繁变动的业务文档。第二类是用HTML或其他中间格式转Word。这种方式对复杂格式的还原度往往不理想，分页、页眉页脚、复杂表格经常出问题，生成的文档打开后格式经常跑偏。第三类就是模板引擎方案，也就是 poi-tl 走的路子。它让设计和数据彻底分离，美工或业务人员用Word 把模板样式排好，开发只管往标签里填数据，两边互不干扰。poi-tl 最大的价值就在于这种彻底的关注点分离：
模板由熟悉 Word 排版的人去做，可以充分利用 Word 本身强大的排版能力，字体、颜色、段落、表格样式随便调
开发人员只需要关心数据从哪来、怎么组织，完全不用操心最终呈现的样式
当业务方要改文档格式时，大多数情况下只需要改一下那个 Word 模板文件，Java 代码一行都不用动。这种解耦带来的维护成本下降，是革命性的。而且 poi-tl 底层站在 Apache POI 的肩膀上，POI 对 Word 格式的支持非常完整可靠，所以 poi-tl 生成的文档格式还原度极高，不会出现那种转换失真的问题。
poi-tl 并没有自己去解析 docx 文件格式，而是直接站在 POI 之上。现代的 docx 文件本质上是一个 zip 压缩包，里面装着一堆遵循 OOXML 标准的 XML 文件，描述了文档的正文、样式、页眉页脚、图片关系等等。Apache POI 负责把这些 XML 解析成可操作的 Java 对象模型，XWPFDocument 代表整个文档、XWPFParagraph 代表段落、XWPFRun 代表一段具有相同格式的文本运行。poi-tl 所有对文档内容的读取和修改，最终都是通过操作 POI 的这些对象来完成的。这也意味着 poi-tl 天生就继承了 POI 对 Word 格式的完整支持能力。
2.第二层：模板解析引擎
当 poi-tl 加载一个 Word 模板时，它会遍历文档里的所有内容，识别出那些符合特定语法规则的标签。poi-tl 的标签默认用一对大括号包裹，比如一个简单的文本标签写作{{variable}}。解析引擎的职责就是扫描整个文档，把散落在正文、表格、页眉页脚里的标签全部找出来，解析成内部的元数据对象，记录下每个标签的类型、名称、所在位置等信息。这里有一个工程上的难点：Word在保存文档时，经常会因为拼写检查、格式微调等原因，把一个连续的标签文本拆分到多个XWPFRun里。你在模板里写的一个完整标签，在底层 XML 可能被切成了好几段。poi-tl 必须能够把这些被切碎的片段重新拼接、正确识别出完整的标签 ，这套文本合并处理的逻辑，是模板解析引擎里相当精巧的一部分。
引入 poi-tl 后，它会自动把所依赖的 Apache POI 相关包（poi、poi-ooxml 等）一起带进来，不需要你手动再引一遍。
⚠️重点提醒：版本匹配问题
这是新手最容易踩的坑，必须单独拿出来说。poi-tl 的每个版本都对 Apache POI 的版本有明确的匹配要求，因为 POI 各大版本之间的 API 会有不兼容的变动。比如 poi-tl 1.12.x 对应的是 POI 5.2.x 系列。如果你的项目里本来就引入了其他版本的 POI，或者像 easyexcel、hutool 这类库间接依赖了不匹配的 POI 版本，就很容易出现NoClassDefFoundError或NoSuchMethodError这类运行时报错。解决办法：在 pom.xml 里用 dependencyManagement 统一锁定 POI 版本，或者用 exclusions 排除掉冲突的传递依赖，确保整个项目的 POI 版本和 poi-tl 要求的一致。这个细节处理好了，能省去大量莫名其妙的排错时间。
第二步：准备模板文件
用 Word 新建一个 docx 文档，把排版样式做好，在需要动态填充的地方按 poi-tl 的语法写上标签。常用的标签语法：
文本标签：{{name}}渲染时替换为字符串
图片标签：{{@logo}} @ 符号表示这是图片标签
• 表格标签：{{#table}} #号表示动态表格• 列表标签：{{*list}} * 号表示列表写好后把这个 docx 文件保存到项目的resources/templates目录下即可。这一步完全在 Word 里完成，不需要写任何代码。
第三步：基础渲染代码（最简版）
poi-tl 的核心 API 非常简洁，最简场景只需要三五行代码：
// 1. 准备数据Map<String, Object> data = new HashMap<>();data.put(“name”, “张三“);data.put(“company”, “某某科技有限公司“);data.put(“date”, “2024年6月“);// 2. 编译模板并渲染XWPFTemplate template = XWPFTemplate.compile(“template.docx”).render(data);// 3. 输出到文件template.writeToFile(“output.docx”);template.close();
@Servicepublic class ContractService {@Autowiredprivate WordGenerator wordGenerator;public byte[] generateContract(Long orderId) throws IOException {// 1. 查询业务数据Order order = orderMapper.selectById(orderId);Customer customer = customerMapper.selectById(order.getCustomerId());// 2. 组装渲染数据Map<String, Object> data = new HashMap<>();data.put(“customerName”, customer.getName());data.put(“amount”, order.getAmount());data.put(“signDate”, LocalDate.now().format(DateTimeFormatter.ofPattern(“yyyy年MM月dd日“)));// 3. 生成文档return wordGenerator.generate(“contract_template.docx”, data);}}
4. Controller层提供下载接口
@GetMapping(“/contract/download/{orderId}”)public void downloadContract(@PathVariable Long orderId,HttpServletResponse response) throws IOException {byte[] bytes = contractService.generateContract(orderId);response.setContentType(“application/vnd.openxmlformats-officedocument.wordprocessingml.document”);response.setHeader(“Content-Disposition”,“attachment;filename=” + URLEncoder.encode(“合同.docx”, StandardCharsets.UTF_8));try (ServletOutputStream out = response.getOutputStream()) {out.write(bytes);out.flush();}}
5.并发安全注意事项
poi-tl 本身的工具类是无状态的，放在 Spring 容器里作为单例使用完全没问题。但要注意一点：同一个XWPFTemplate实例不要在多个线程间共享渲染。每次请求都应该重新 compile + render，生成独立的文档对象。因为底层的 POI 文档对象不是线程安全的，并发修改同一个文档实例会出问题。按上面的写法，每次请求都新建 template，用完就关，天然就是线程安全的。
夜雨聆风
