简介：一套用于将数据库信息自动生成为Word表格文档的C#实现资源包，面向需要处理报表生成、数据导出的.NET开发者或IT运维人员，能有效替代手工整理数据库结构信息的繁琐工作。压缩包共230个文件，大小仅2.62MB，包含51个C#源码文件、动态链接库、调试符号，以及数据库连接配置、SQL查询脚本和可运行的exe示例，便于直接查看效果或二次开发。资源涉及使用ADO.NET连接SQL Server等数据库、遍历表与字段信息，并通过Office Interop或第三方库在Word中生成表格的核心流程，同时附有完整项目工程文件与文档样例，可作为即用的学习模板。已有429人浏览学习，对于需要快速掌握“数据库转Word”自动化编程的读者，这是一份轻量且实用的参考。

1. 数据库里的数据，怎么变成一份能交付的Word文档

做企业内部系统的人，大概率都接过这样的需求：把数据库里的合同、台账、检测报告、人员信息导成Word文档，发给客户或留档。手工复制粘贴第一回还能忍，数据一上千条、格式一变再变，人就废了。程序实现数据库生成Word文档，说白了就是把数据库里的结构化数据，按一套预先设计好的模板，自动拼装成一份格式正确的docx文件。它不是让你在代码里徒手画Word，而是让程序替代人工完成“查数据→填模板→导出文件”这条流水线。

这个方向适合谁？适合正在做办公自动化、报表导出、电子签章前置处理的开发者和运维人员。哪怕你只用过MySQL加一点Java或Python，也能在半天内跑通第一版。我下面给的方案，不是某个特定框架的说明书，而是我自己反复用的一条稳定路径：用模板引擎渲染Word，数据从数据库来，产物是标准docx。你照着做，至少能避开“格式乱掉”“中文乱码”“内存爆炸”这几个最常见的翻车点。

2. 先搞清楚用哪种程序方案：模板渲染完胜手动拼文档

2.1 为什么不用POI代码硬画Word

很多人第一反应是用Apache POI在代码里逐行创建段落、表格、样式。这个思路能跑通，但它把“文档结构”硬编码进了程序里。业务人员改一个标题、加一行说明，都得找开发改代码、重新发版。更麻烦的是，POI直接操作XWPFParagraph和XWPFRun时，样式控制非常琐碎，一个字体加粗、一个行距调整，都要写好几行。程序逻辑一多，出来的文档经常出现“标题对不上”“表格变形”这种说不清的玄学问题。

我一般会用模板渲染替代硬编码。先把Word文档做成一个带占位符的模板文件，程序只负责从数据库查数据、把数据填进占位符，文档结构完全由模板决定。业务方要改格式，直接改模板，不用动代码。这个思路跟我做过的大多数报表导出需求吻合：格式归格式，数据归数据，程序只做映射。

2.2 选型对比：POI-TL、Freemarker XML模板、docx4j怎么选

选型时我列过一张对比表，给你参考。

日常项目里，我最常用POI-TL。它支持{{name}}这种简单占位符，也支持表格循环、图片渲染，对中文支持好，社区也活跃。需要强调一句：POI-TL本身不连接数据库，它只负责“数据→Word”这一段。数据从MySQL还是Oracle来，由你的业务代码去查，查完组装成一个Map或对象，扔给POI-TL渲染。这个边界一定要清楚，否则会把简单的事情搞复杂。

2.3 整体实现路径：从数据库表到docx文件的四步骨架

无论是用哪种语言，整个链路的骨架都一样。第一步，定义模板：在Word里写好感占位符，另存为docx。第二步，查数据：通过JDBC、MyBatis、Spring Data JPA等方式从数据库查出需要的记录，转成Java对象或Map。第三步，组装模型：把查询结果整理成POI-TL需要的Map结构，列表数据用List包装。第四步，渲染输出：调用POI-TL的API，把模板和数据模型合成最终的docx文件，写入本地磁盘或上传到文件服务。

后面两章我会展开第三步和第四步的具体代码。这里先给你吃一颗定心丸：这个方案不需要你对Word文件格式有深入理解，只要你会写SQL、会用Java操作Map，就能在半小时内跑通最小示例。模板部分业务人员也能参与维护，程序端就是纯粹的“取数+填充”。

3. 从MySQL取数到docx的最小可运行程序

3.1 准备一个带占位符的docx模板

模板是这个方案的灵魂。打开Word，新建一份文档，按你最终想要的格式排版好，然后把需要动态变化的地方替换成占位符。占位符的语法由渲染引擎决定。以POI-TL为例，普通文本占位符写成{{name}}，表格循环区域在循环行首列写{{?list}}，循环结束在对应的行尾列写{{/list}}。这个语法在官方文档里有完整说明，但最常见的就这几种。

我建议模板里的占位符命名和数据库字段名保持一致，这样组装Map时不用做大量改名映射。比如数据库字段叫customer_name，占位符就叫{{customer_name}}。字段一多，这套约定能省下不少排查时间。模板存哪里都行，本地磁盘、classpath、OSS都支持，但要注意：模板文件必须保证是Word能正常打开的docx格式，不要用别人发来的“假docx”（有些在线工具生成的docx其实是个HTML文件改后缀）。

提示：模板定稿前，先人工用真实的几行数据替换占位符，看排版效果。这一步能发现90%的格式问题，别等到程序写完再返工。

3.2 最小可复现示例：Java + POI-TL + MySQL

下面这段代码是完整的最小示例，跑通它，你就拥有了一个“数据库生成Word文档”的雏形。我以Spring Boot项目为例，但核心逻辑不依赖Spring，你用纯JDBC也能套用。

先加依赖。如果你是Maven项目，在pom.xml里加POI-TL的坐标：

<dependency> <groupId>com.deepoove</groupId> <artifactId>poi-tl</artifactId> <version>1.12.1</version> </dependency>

版本不用跟我完全一致，选Maven中央仓库里的最新稳定版即可。这个库会把POI一并引进来，所以你不需要单独再引poi。

然后是核心代码。我写了一个Service方法，逻辑是：从contract表里查出中标通知书的数据，填模板，生成docx。数据库连接用Spring的JdbcTemplate，查询结果手动转成Map。

import com.deepoove.poi.XWPFTemplate; import com.deepoove.poi.config.Configure; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.stereotype.Service; import java.io.FileOutputStream; import java.io.IOException; import java.util.HashMap; import java.util.List; import java.util.Map; @Service public class ContractWordService { private final JdbcTemplate jdbcTemplate; public ContractWordService(JdbcTemplate jdbcTemplate) { this.jdbcTemplate = jdbcTemplate; } public void generateContractWord(Long contractId) throws IOException { // 第一步：根据ID查出主表数据，结果用Map承载 Map<String, Object> dataMap = jdbcTemplate.queryForMap( "SELECT contract_no, project_name, customer_name, sign_date, amount " + "FROM contract WHERE id = ?", contractId); // 第二步：查出明细列表，用于模板里的表格循环 List<Map<String, Object>> items = jdbcTemplate.queryForList( "SELECT item_name, spec, unit, quantity FROM contract_item WHERE contract_id = ?", contractId); // 第三步：组装渲染模型 Map<String, Object> root = new HashMap<>(dataMap); root.put("itemList", items); // 第四步：渲染模板并输出 String templatePath = "templates/contract_template.docx"; String outputPath = "output/contract_" + contractId + ".docx"; try (XWPFTemplate template = XWPFTemplate.compile(templatePath, Configure.createDefault())) { template.render(root); template.write(new FileOutputStream(outputPath)); } } }

这段代码的逻辑我拆开讲一下。queryForMap返回的是字段名到值的映射，字段名就是SQL里的列名，正好和模板占位符对应。queryForList同理，返回多条Map记录。组装root时，明细列表的key是itemList，对应模板里表格循环的{{?itemList}}。最后用XWPFTemplate.compile加载模板，render填充数据，write写出文件，资源用try-with-resources自动关闭。

两个需要重点理解的参数：第一，模板路径templatePath，建议放在src/main/resources/templates下，这样打包进jar也能找到；第二，Configure.createDefault()，默认配置不做任何自定义，如果模板里用了图片或特殊策略，这里要改成对应的配置对象，我后面会讲到。输出文件名加上contractId，避免并发导出时互相覆盖，这是个小小的好习惯。

3.3 模板表格的循环语法：让数据行数自动扩展

如果文档里有一张明细表，行数不固定，就得用POI-TL的表格循环策略。做法是：在Word里画好一行示例行，在这一行的第一个单元格写{{?itemList}}，在最后一个单元格写{{/itemList}}，中间每格写{{字段名}}。渲染时，POI-TL会复制这一行，循环填数据，行数跟List的元素个数一致。

我实际踩过的坑是：循环标记必须放在表格单元格内部，不能放在表格外面的段落里；而且{{?itemList}}和{{/itemList}}必须成对出现，写错一个，渲染时直接报错或表格不展开。举个例子，一个四列的明细表，模板单元格内容分别是：

{{?itemList}} {{item_name}} {{spec}} {{unit}} {{quantity}} {{/itemList}}

渲染完的表格，自动变成每条记录一行。这个语法看起来简单，但它解决的是“行数动态变化”的核心问题。你在代码里除了准备数据，其他什么都不用做。当初我第一次用的时候，还在纠结要不要在Java代码里拼接表格行——完全不用，模板引擎帮你干了。

提示：表格循环只对“行”循环生效，不要试图对列做循环。列数固定、行数动态，这是Word导出的基本现实，遇到列数也要动态的场景，建议换另一个方案：先程序生成CSV，再让用户打开Word插入表格，别硬刚。

4. 进阶落地：从“能跑通”到“敢上线”的几个必做改造

4.1 图片动态渲染：把数据库里的路径变成Word里的图

合同扫描件、产品照片、人员头像这类数据，数据库里存的一般是文件路径或URL。POI-TL渲染图片需要用PictureRenderData这个对象包装。假设contract表里有一个signature_image字段，存的是图片文件在服务器上的绝对路径，代码改造如下：

import com.deepoove.poi.data.PictureRenderData; // 查图片路径 String imagePath = (String) dataMap.get("signature_image"); if (imagePath != null && !imagePath.isEmpty()) { // 第二个参数是宽，第三个是高，单位是像素，按模板需要调整 dataMap.put("signature_image", new PictureRenderData(120, 60, imagePath)); }

模板里依然写{{signature_image}}。需要注意：占位符会随图片大小一起替换，如果图片尺寸不合适Word里直接显示很大或很小，建议图片的宽高在代码里写死，因为不同机器上同一张图片的原始尺寸可能不一样，写死才能保证排版稳定。另外，图片格式尽量用jpg或png，gif的兼容性差点，之前在Linux服务器上渲染gif时出现过偶尔不显示的情况。

4.2 文件输出策略：本地路径、OSS还是FastDFS

生成的docx写到哪？小项目直接写本地磁盘就行。用FileOutputStream输出时，注意目录要先创建，Java不会自动建父目录。写法很简单：

File outFile = new File(outputPath); if (!outFile.getParentFile().exists()) { outFile.getParentFile().mkdirs(); }

但上线之后，服务器通常是集群部署，本地磁盘不共享，用户下载会出现“在这台机器生成、在另一台机器找不到文件”的窘境。常见做法是：生成完docx后，立即上传到文件服务（MinIO、FastDFS、阿里云OSS等），然后把可访问的URL存到数据库里，最后删除本地临时文件。这样既保证文件可访问，又不占用服务器磁盘。上传部分用各自SDK的putObject方法，这里不展开，但思路一定要提前定好：本地磁盘只当中转站，不是终点。

4.3 并发与内存控制：大数据量导出别把JVM撑爆

导出几千条明细数据时，POI操作的是内存中的XWPFDocument，几十MB的数据就可能让堆内存告急。我有两个习惯：第一，用XWPFTemplate时尽量不用静态单例持有文档对象，渲染用完即关；第二，明细查询不要一次查出全表，用分页或游标。

分页逻辑的代码模式长这样：

int pageSize = 500; int pageNum = 0; List<Map<String, Object>> pageData; do { pageData = jdbcTemplate.queryForList( "SELECT item_name, spec, unit, quantity FROM contract_item " + "WHERE contract_id = ? LIMIT ? OFFSET ?", contractId, pageSize, pageNum * pageSize); // 把这个分页的数据写入一个临时模板片段，或累积到一定量再整体渲染 pageNum++; } while (pageData.size() == pageSize);

说实话，POI-TL对超大数据量支持一般。如果你要导出的Word本身就是上千页的报表，我更推荐先按章节切成多个模板片段，分别渲染后再用docx4j合并，或者直接放弃Word、改用PDF导出。Word本质上不是为海量数据设计的，别跟它较劲，这是血泪经验。

4.4 异步任务和状态追踪：超时不想让用户盯着页面

文档生成本来就是I/O密集操作，数据一多可能耗时十几秒到几分钟。这种情况下，别在HTTP请求里同步生成，用户很快就超时了。我常用方案是把任务丢进线程池或消息队列，先返回一个任务ID，前端轮询查状态，生成完后展示下载链接。

线程池写法不复杂，但要注意：线程池的队列长度和拒绝策略要实现好，否则系统一忙就丢任务。状态存数据库时，至少记三个字段：task_status（处理中/成功/失败）、task_message（失败原因）、file_url（生成后的下载地址）。这一步做完，这个模块才真正算“敢上线”了。

5. 数据库生成Word的避坑指南：五类典型问题与排查路径

5.1 占位符没被替换，原样输出在文档里

现象：生成的Word里出现了{{customer_name}}这种原文，数据没填进去。

原因有几种：模板里占位符写错，比如多了空格，写成{{ customer_name }}；或者数据模型里没有customer_name这个key；又或者占位符落在表格里但表格没有启用循环策略。

解决：先检查模板占位符是否和代码渲染时的key完全一致，包括大小写。再打印root的key集合，确认数据模型有值。最后确认占位符是否在表格内，如果在表格内且没写循环标记，POI-TL的默认行为是不处理。我排查时习惯写一行调试代码：

System.out.println(root.keySet());

一眼就能看出问题。

5.2 中文乱码或字体变成宋体，领导说格式不对

现象：生成的文档中文显示正常，但字体不是模板里设的字体，或者打开时提示字体缺失。

原因：docx模板里的字体如果用的是系统没有的字体，渲染时会被替换。服务器如果是精简版Linux，缺中文字体是家常便饭。

解决：模板里尽量用通用字体，Windows上默认宋体、微软雅黑在Linux服务器不一定有，建议服务器安装fonts-wqy-microhei或者fontconfig。另外，POI-TL默认渲染不会覆盖模板字体设置，如果你在代码里用Configure创建时自定义了样式，反而会覆盖模板，所以没特殊需求就保持默认。若文档要求必须用某字体，就把它连同字库文件一起让运维装到服务器上。

5.3 图表或特殊符号显示成红色感叹号

现象：文档里插入的图标、箭头、特殊符号，渲染后变成红色的“!”或者一个空框。

原因：docx本质上是个zip包，内部用XML描述内容。POI-TL在处理复杂对象（比如数学公式、某些域代码）时会丢失部分引用，尤其是有VML图形或OLE对象的模板。

解决：别在模板里放复杂对象。需要图形标识就用普通图片代替；需要公式，建议用图片方式插入；需要编号，用Word自带的列表功能而不是手动敲数字。这条规则我没找到完美的破解方法，分享一个折中经验：模板越接近“纯文本+表格+图片”，渲染越稳定，花哨的东西越少越好。

5.4 数据库字段为null，文档里出现“null”字符串

现象：某条记录的备注字段为空，生成的Word里赫然写着“null”两个字。

原因：程序把Java的null直接丢给渲染引擎，POI-TL默认输出null字符串。业务上不想要这四个字母。

解决：组装模型前做一次空值处理，这是我自己一直坚持的规范。封装一个方法：

private String nullToEmpty(Object val) { return val == null ? "" : val.toString(); }

所有可能为空的字段过一遍这个方法再放进root。别嫌麻烦，这个坑几乎每个人都会遇到一次，代码里提前处理掉，后面就没那么多扯皮。

5.5 并发导出时文件互相覆盖或报文件占用

现象：两个人同时点击导出，生成的文件内容串了，或者提示“文件被占用”。

原因：输出文件名固定，或者两个请求在同一时刻往同一个文件路径写。

解决：输出文件名加唯一标识，我用的是“业务ID+时间戳+随机数”拼接。另外，写文件要同步，每个任务写一个独立文件，不要共享同一个FileOutputStream。上传文件服务后，本地文件及时删除，也能避免磁盘被临时文件塞满。

6. 验证模板与数据的对应关系：一个能提前兜底的检查脚本

最后想跟你分享一个我一直在用的验证习惯——检查模板里的占位符和代码里的数据模型对不对得上。这个操作能在大批量文档导出前把大多数低级错误挡在门外。我用Java写了一个简单的扫描方法，把模板里所有占位符提取出来，和代码里准备的数据key做比对，缺失的打印警告。

思路是用正则匹配模板文件中的{{...}}：

import java.util.regex.Matcher; import java.util.regex.Pattern; public class TemplateValidator { public static void validate(String templatePath, Map<String, Object> data) throws IOException { // 模板文件本质是zip，这里简化处理：用POI-TL的模板对象读取 XWPFTemplate template = XWPFTemplate.compile(templatePath); String content = template.getXWPFDocument().getText(); Pattern pattern = Pattern.compile("\\{\\{([^}]+)}}"); Matcher matcher = pattern.matcher(content); while (matcher.find()) { String key = matcher.group(1).trim(); // 跳过循环标记 if (key.startsWith("?") || key.startsWith("/")) { continue; } if (!data.containsKey(key)) { System.err.println("警告：模板中的占位符[" + key + "]在数据模型中不存在"); } } template.close(); } }

这个方法虽然粗糙，但能快速暴露占位符拼写不一致的问题。我自己每次改完模板或改完SQL，都先跑一次这个检查再全量导出，省下的返工时间不可估量。

再补一个进阶技巧：如果模板里有一批固定前缀的字段，比如所有以“cust_”开头的字段都从customer表来，可以在代码里用数据库元信息反射生成数据模型，减少手写key映射。Java的JdbcTemplate查询返回的Map本身就是列名到值的映射，所以只要“模板占位符名=数据库列名”这个约定立住，跨表查完拼Map就是纯粹体力活。

这套方案的边界我也跟你交个底：它适合结构化数据导出，不适合复杂排版、动态列、多级目录自动生成这类需求。碰到那种场景，先跟业务方确认是不是真的非得Word不可。这些年我学到的教训是，跟Word格式较劲不如跟业务方聊清楚需求边界。希望帮到你。

本文还有配套的精品资源，点击获取