使用 Java 和 FreeMarker 实现自动生成供货清单，动态生成 Word 文档，简化文档处理流程。

在上一篇博客中主要是使用SpringBoot+Apache POI实现了BOM物料清单Excel表格导出，详见以下博客：

Spring Boot + Apache POI 实现 Exc（）el 导出：BOM物料清单生成器（支持中文文件名、样式美化、数据合并）

---

目录

引言

项目结构

源代码展示

1.WordController

2.WordUtil工具类

3.FreeMarker模版

4.POM依赖

WordController类深度解析

1.类结构

2.main方法

3.generateWordFile方法

4.addTestData方法

WordUtil类深度解析

1.类结构和静态成员

2.静态初始化块

3.私有构造函数

4.exportMillCertificateWord方法

5.createDoc方法

6.WordUtil类总结

FreeMarker模板深度解析

1.文档结构和样式

2.表格结构和动态数据插入

总结

---

引言

在电缆行业，生成供货清单是一项常见但繁琐的任务。本教程将介绍如何使用现代Java技术栈自动化这一过程，大幅提高工作效率和准确性。我们将使用SpringBoot作为框架，Apache POI处理Word文档，以及FreeMarker作为模板引擎来实现这一功能！

让我们先了解一下这个问题的背景:

1. 在电缆行业，手动创建供货清单是一个复杂且重复的过程。
2. 这个过程不仅耗时，还容易出错，影响工作效率和数据准确性。

为了解决这个问题,我们提出了一个技术方案,结合了以下几个关键技术:

1. SpringBoot: 作为我们的主要开发框架
2. Apache POI: 用于生成和操作Word文档
3. FreeMarker模板引擎: 用于生成Word文件的内容

这个方案的主要优势包括:

1. 灵活性: 使用FreeMarker模板可以轻松调整文档格式,而无需修改程序代码。
2. 效率: 自动化生成过程大大减少了人工操作,提高了办公效率。
3. 准确性: 自动化处理确保了数据的准确性和一致性。
4. 适用性: 特别适合电缆行业的业务需求，生成符合要求的.doc文件。

通过阅读这篇博客，您将学习如何实现这个解决方案，从而帮助您或您的团队简化工作流程,提高生产效率。

效果图：

项目结构

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── pw/
│   │           ├── WordController.java  #负责生成测试数据并调用WordUtil工具类来生成Word文档
│   │           └── utils/
│   │               └── WordUtil.java  #这个工具类封装了使用FreeMarker生成Word文档的核心功能
│   └── resources/
│       └── templates/
│           └── template.ftl #模版定义了Word文档的结构和样式，使用HTML和CSS来格式化内容

1.WordController类：这个类是我们应用的入口点，负责生成测试数据并调用WordUtil来生成Word文档。

2.WordUtil类：这个工具类封装了使用FreeMarker生成Word文档的核心逻辑。

3.FreeMarker模版（template.ftl）:这个模版定义了Word文档的结构和样式，使用HTML和CSS来格式化内容。

源代码展示

1.WordController

import com.pw.utils.WordUtil;

import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class WordController {

    public static void main(String[] args) throws IOException {
        // 指定保存Word文件的目录
        String filePath = "F:\\Poi2Word\\src\\main\\resources\\output"; // 更改为您希望的目录
        new WordController().generateWordFile(filePath);
    }

    public void generateWordFile(String directory) throws IOException {
        List> listMap = new ArrayList<>();

        //测试数据
        addTestData(listMap, "4600025747", "绝缘导线", "AC10kV,JKLYJ,300", 1500, "米", "盘号：A1");
        addTestData(listMap, "4600025748", "绝缘导线", "AC10kV,JKLGYJ,150/30", 2500, "米", "盘号：A2");
        addTestData(listMap, "4600025749", "绝缘导线", "AC10kV,JKLGYJ,150/30", 3500, "米", "盘号：A3");
        addTestData(listMap, "4600025750", "绝缘导线", "AC10kV,JKLGYJ,150/30", 4500, "米", "盘号：A4");
        addTestData(listMap, "4600025751", "绝缘导线", "AC10kV,JKLGYJ,150/30", 3800, "米", "盘号：A5");
        addTestData(listMap, "4600025752", "绝缘导线", "AC10kV,JKLYJ,180", 2000, "米", "盘号：A6");
        addTestData(listMap, "4600025753", "绝缘导线", "AC10kV,JKLYJ,120", 4200, "米", "盘号：A7");
        addTestData(listMap, "4600025754", "绝缘导线", "AC10kV,JKLYJ,120", 3700, "米", "盘号：A8");
        addTestData(listMap, "4600025755", "绝缘导线", "AC10kV,JKLYJ,120", 4300, "米", "盘号：A9");
        addTestData(listMap, "4600025756", "绝缘导线", "AC10kV,JKLGYJ,100/20", 2800, "米", "盘号：A10");
        addTestData(listMap, "4600025757", "绝缘导线", "AC10kV,JKLGYJ,100/20", 2400, "米", "盘号：A11");
        addTestData(listMap, "4600025758", "绝缘导线", "AC10kV,JKLGYJ,100/20", 2600, "米", "盘号：A12");

        HashMap map = new HashMap<>();
        map.put("qdList", listMap);  // 添加供货清单数据
        map.put("contacts", "张三");  // 联系人
        map.put("contactsPhone", "13988887777");  // 联系电话
        map.put("date", "2025年01月18日");  // 日期
        map.put("company", "新电缆科技有限公司");  // 公司名称
        map.put("customer", "国网北京市电力公司");  // 客户

        String wordName = "template.ftl"; // FreeMarker模板文件名
        String fileName = "供货清单" + System.currentTimeMillis() + ".doc"; // 带时间戳的文件名
        String name = "name";  // 临时文件名

        // 确保输出目录存在
        File directoryFile = new File(directory);
        if (!directoryFile.exists()) {
            directoryFile.mkdirs();  // 如果目录不存在则创建
        }

        // 生成Word文件
        WordUtil.exportMillCertificateWord(directory, map, wordName, fileName, name);

        System.out.println("文件成功生成在：" + directory + fileName);
    }

    private void addTestData(List> listMap, String danhao, String name, String model, int num, String unit, String remark) {
        Map item = new HashMap<>();
        item.put("serNo", listMap.size() + 1);  // 序号
        item.put("danhao", danhao);  // 单号
        item.put("name", name);  // 产品名称
        item.put("model", model);  // 规格型号
        item.put("num", String.valueOf(num));  // 数量，转换为字符串
        item.put("unit", unit);  // 单位
        item.put("remark", remark);  // 备注
        listMap.add(item);  // 将数据添加到列表
    }
}

2.WordUtil工具类

package com.pw.utils;

import freemarker.template.Configuration;
import freemarker.template.Template;

import java.io.*;
import java.util.Map;

public class WordUtil {
    private static Configuration configuration = null;

    // 模板文件夹路径
    private static final String templateFolder = WordUtil.class.getResource("/templates").getPath();

    static {
        configuration = new Configuration();
        configuration.setDefaultEncoding("utf-8");
        try {
            System.out.println(templateFolder);
            configuration.setDirectoryForTemplateLoading(new File(templateFolder));  // 设置模板加载路径
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    private WordUtil() {
        throw new AssertionError();  // 防止实例化
    }

    /**
     * 导出Word文档
     * @param map Word文档中参数
     * @param wordName 模板的名字，例如xxx.ftl
     * @param fileName Word文件的名字 格式为："xxxx.doc"
     * @param outputDirectory 输出文件的目录路径
     * @param name 临时的文件夹名称，作为Word文件生成的标识
     * @throws IOException
     */
    public static void exportMillCertificateWord(String outputDirectory, Map map, String wordName, String fileName, String name) throws IOException {
        Template freemarkerTemplate = configuration.getTemplate(wordName);  // 获取模板文件
        File file = null;
        try {
            // 调用工具类的createDoc方法生成Word文档
            file = createDoc(map, freemarkerTemplate, name);

            // 确保输出目录存在
            File dir = new File(outputDirectory);
            if (!dir.exists()) {
                dir.mkdirs();  // 如果目录不存在则创建
            }

            // 定义完整的文件路径
            File outputFile = new File(outputDirectory, fileName);

            // 重命名并移动文件到指定目录
            file.renameTo(outputFile);

            System.out.println("文件成功生成在: " + outputFile.getAbsolutePath());
        } finally {
            if (file != null && file.exists()) {
                file.delete();  // 删除临时文件
            }
        }
    }

    private static File createDoc(Map dataMap, Template template, String name) {
        File f = new File(name);
        try {
            // 使用OutputStreamWriter来指定编码，防止特殊字符出问题
            Writer w = new OutputStreamWriter(new FileOutputStream(f), "utf-8");
            template.process(dataMap, w);  // 使用FreeMarker处理模板
            w.close();
        } catch (Exception ex) {
            ex.printStackTrace();
            throw new RuntimeException(ex);
        }
        return f;  // 返回生成的文件
    }
}

3.FreeMarker模版

    
    
    


${company}送货清单
  


    <#assign totalQuantity = 0>  
    <#assign totalItems = 0>  
    <#assign sortedList = qdList?sort_by("model")>  
    <#assign currentModel = "">  
    <#assign subtotalQuantity = 0>  
    <#assign subtotalItems = 0>  
    <#list sortedList as item>  
        <#if item.model != currentModel>  
            <#if currentModel != "">  
            <#assign currentModel = item.model>  
            <#assign subtotalQuantity = 0>  
            <#assign subtotalItems = 0>  
        <#assign itemNum = item.num?replace(",", "")?number>  
        <#assign subtotalQuantity = subtotalQuantity + itemNum>  
        <#assign subtotalItems = subtotalItems + 1>  
        <#assign totalQuantity = totalQuantity + itemNum>  
        <#assign totalItems = totalItems + 1>  
    <#if currentModel != "">  

    

        
序号
  
        
供货单号
  
        
产品名称
  
        
规格型号
  
        
数量
  
        
单位
  
        
备注
  
    

                

                    
小计：${subtotalQuantity}${sortedList[0].unit} ${subtotalItems}轴
                    
${subtotalQuantity}
                    
${sortedList[0].unit}
                    

                
            
        
        

            
${item?counter}
  
            
${item.danhao}
  
            
${item.name}
  
            
${item.model}
  
            
${item.num}
  
            
${item.unit}
  
            
${item.remark}
  
        

    
        

            
小计：${subtotalQuantity}${sortedList[0].unit} ${subtotalItems}轴
            
${subtotalQuantity}
            
${sortedList[0].unit}
            

        
    
    

        
合计：${totalQuantity}${qdList[0].unit} ${totalItems}轴
        
${totalQuantity}
        
${qdList[0].unit}
        

    


发货联系人：${contacts}
  
联系电话：${contactsPhone}
  
日期：${date}
  

收货人（签字）：_______________
  
联系电话：_______________
  
${customer}
  

4.POM依赖

    org.springframework.boot
    spring-boot-starter-freemarker



    org.apache.poi
    poi
    5.0.0



    org.apache.poi
    poi-ooxml
    5.0.0



    org.apache.poi
    ooxml-schemas
    1.4

WordController类深度解析

WordController类是整个应用的核心控制器，负责协调数据生成和文档创建的过程。让我们逐步分析它的主要组成部分：

1.类结构

public class WordController {
    // 方法定义...
}

这个类没有继承任何其他类，也没有实现任何接口，是一个独立的控制器类。

2.main方法

public static void main(String[] args) throws IOException {
    String filePath = "F:\\Poi2Word\\src\\main\\resources\\output";
    new WordController().generateWordFile(filePath);
}

• 这是应用的入口点。
• 它设置了输出文件的路径,然后调用generateWordFile方法。
• 请注意：在常规的 Spring Boot 实际应用场景下，我们一般不会直接在控制器类中使用 main 方法。此处之所以将 main 方法置于控制器中，纯粹是出于演示目的，旨在让相关流程更加直观易懂。

而当进入到正式开发环节时，有几个关键要点务必落实：

其一，需要引入数据库集成功能，将当前所使用的测试数据全面替换为从数据库中精准查询获取的真实数据，以此确保数据的准确性与时效性；

其二，要对控制器进行优化改造，摒弃现有的演示模式，将其转换为遵循标准规范的请求接口实现方式，进而满足实际业务需求，提升系统的稳定性与可扩展性。

3.generateWordFile方法

此方法的只要目的是生成Word文件，首先需要先收集和存储测试数据，存储表格数据是将一条数据存储在Map集合中，再将每一条数据存储到List集合中。将其他数据存储到单独的一个Map集合中。然后确保输出目录存在，最后调用WordUtil中的exportMillCertificateWord方法生成文件，并输出文件的生成位置。

// 生成 Word 文件的方法
public void generateWordFile(String directory) throws IOException {
    // 存储测试数据的列表，每个元素都是一个 Map，存储了具体的信息
    List> listMap = new ArrayList<>();

    // 添加测试数据，调用 addTestData 方法添加一条记录
    addTestData(listMap, "4600025747", "绝缘导线", "AC10kV,JKLYJ,300", 1500, "米", "盘号：A1");
    //... 可以继续调用 addTestData 方法添加更多测试数据...

    // 存储最终要填充到 Word 模板的数据的 Map，包含各种信息
    HashMap map = new HashMap<>();
    // 将测试数据列表添加到 map 中，键为 "qdList"
    map.put("qdList", listMap);
    // 联系人信息
    map.put("contacts", "张三");
    // 联系人电话
    map.put("contactsPhone", "13988887777");
    // 日期信息
    map.put("date", "2025年01月18日");
    // 公司名称
    map.put("company", "新电缆科技有限公司");
    // 客户名称
    map.put("customer", "国网北京市电力公司");

    // Word 模板文件的名称
    String wordName = "template.ftl";
    // 生成的 Word 文件的名称，使用当前时间戳保证文件名的唯一性
    String fileName = "供货清单" + System.currentTimeMillis() + ".doc";
    // 名称信息，具体含义可能根据实际情况而定
    String name = "name";

    // 创建一个文件对象，用于表示输出目录
    File directoryFile = new File(directory);
    // 检查输出目录是否存在，如果不存在则创建目录
    if (!directoryFile.exists()) {
        directoryFile.mkdirs();
    }

    // 调用 WordUtil 的 exportMillCertificateWord 方法生成 Word 文件
    // 传入目录、数据 Map、模板名称、生成的文件名称和名称信息
    WordUtil.exportMillCertificateWord(directory, map, wordName, fileName, name);

    // 打印生成文件的成功信息
    System.out.println("文件成功生成在：" + directory + fileName);
}

这个方法完成以下任务：

• 创建一个一个List>集合来存储供货清单数据
• 使用addTestData方法添加多条测试数据
• 创建一个Map集合来存储企业名称，发货联系人，联系电话等信息
• 确保输出目录存在
• 调用WordUtil.exportMillCertificateWord方法来生成Word文档

4.addTestData方法

这个方法用于创建单个供货项目的数据

// 添加一条测试数据到 listMap 中
private void addTestData(List> listMap, String danhao, String name, String model, int num, String unit, String remark) {
    // 创建一个新的 HashMap，用于存储每一条数据
    Map item = new HashMap<>();
    
    // 将数据项依次放入 HashMap 中，"serNo" 表示序号，使用 listMap 的大小+1 生成序号
    item.put("serNo", listMap.size() + 1);  // 序号是当前列表的大小 + 1
    item.put("danhao", danhao);  // 供货单号
    item.put("name", name);  // 产品名称
    item.put("model", model);  // 规格型号
    item.put("num", String.valueOf(num));  // 数量，将整数转为字符串
    item.put("unit", unit);  // 单位
    item.put("remark", remark);  // 备注
    
    // 将该条数据项添加到 listMap 列表中
    listMap.add(item);
}

这个方法完成以下任务：

• 它接收多个参数,代表一个供货项目的各个属性。
• 创建一个新的Map来存储这个项目的数据。
• 自动计算序号(serNo)基于当前列表的大小。
• 将所有数据添加到Map中。
• 将这个Map添加到供货清单列表中。

WordUtil类深度解析

WordUtil类是整个文档生成过程的核心，它封装了FreeMarker模板引擎的配置和使用逻辑。让我们逐步分析它的主要组成部分：

1.类结构和静态成员

public class WordUtil {
    private static Configuration configuration = null;
    private static final String templateFolder = WordUtil.class.getResource("/templates").getPath();
    
    // 其他方法...
}

configuration：这是FreeMarker的核心配置对象，用于设置模版加载路径。

templateFolder：定义了模版文件的存储路径。使用getResource()方法确保在不同环境下都能正确找到模版文件。

2.静态初始化块

这段代码的作用是初始化FreeMarker的Configuration对象，设置模版加载目录以及编码格式，以便FreeMarker后续能够正确加载和处理模版文件。

// 静态初始化块，用于初始化 FreeMarker 配置
static {
    // 创建一个 FreeMarker 配置对象，用于后续模板处理
    configuration = new Configuration();
    
    // 设置 FreeMarker 配置对象的默认编码为 "utf-8"
    configuration.setDefaultEncoding("utf-8");
    
    try {
        // 输出模板文件夹路径，帮助调试
        System.out.println(templateFolder);
        
        // 设置模板加载目录为 templateFolder 指定的路径，模板文件会从该目录加载
        configuration.setDirectoryForTemplateLoading(new File(templateFolder));
    } catch (IOException e) {
        // 如果加载模板目录时出现异常，打印错误堆栈信息
        e.printStackTrace();
    }
}

这个静态初始化块在类加载时执行，主要完成以下任务：

• 创建FreeMarker的Configuration对象
• 设置默认编码为UTF-8，确保正确处理中文等字符
• 设置模版加载目录，这样FreeMarker就知道从哪里查找加载模版文件了
• 错误处理：如果执行过程中出现了IO异常，就会打印堆栈跟踪

3.私有构造函数

这个构造函数防止类被实例化,确保WordUtil只能通过其静态方法使用。

private WordUtil() {
    throw new AssertionError();
}

私有构造函数的好处包括：

• 防止类被实例化

当类的构造函数被声明为private时，外部代码无法直接创建该类的实例。这就意味着该类只能公国静态方法访问，确保类的功能是全局共享的。

• 实现单例模式的基础

在一些设计模式中，例如单例模式，类只允许有一个实例，私有构造函数确保了这一点。通过private构造函数，我们可以控制类的实例化过程，并确保只有一个实例被创建。

• 封装类的内部实现

私有构造函数可以帮助隐藏类的具体实现细节，外部代码不需要关心如何创建类的实例，只需要使用类提供的静态方法即可。这增加了类的封装性，降低了与外部代码的耦合度。

• 避免多余的对象创建

由于无法实例化类，每次调用静态方法时，都会使用已有的类实例，这可以避免无意义的对象创建，节省内存和资源。

4.exportMillCertificateWord方法

这个方法的主要功能是通过加载指定的 FreeMarker 模板生成一个临时的 Word 文档，确保输出目录存在后，将临时文件重命名并保存到指定的位置，同时在过程结束后清理临时文件，并打印文件生成的成功消息。

// 导出 Word 文档的方法
public static void exportMillCertificateWord(String outputDirectory, Map map, String wordName, String fileName, String name) throws IOException {
    // 获取 FreeMarker 模板文件
    Template freemarkerTemplate = configuration.getTemplate(wordName);
    // 初始化一个 File 对象，用于存储生成的临时文件
    File file = null;
    
    try {
        // 使用模板和数据创建 Word 文档，返回临时文件
        file = createDoc(map, freemarkerTemplate, name);
        
        // 创建目标目录的 File 对象
        File dir = new File(outputDirectory);
        
        // 如果目录不存在，则创建该目录
        if (!dir.exists()) {
            dir.mkdirs();  // 创建目录及其父目录
        }
        
        // 定义最终输出文件的完整路径（包括目录和文件名）
        File outputFile = new File(outputDirectory, fileName);
        
        // 将临时生成的文件重命名为目标文件，并将其移动到指定目录
        file.renameTo(outputFile);
        
        // 打印输出文件的绝对路径，a通知文件生成成功
        System.out.println("文件成功生成在: " + outputFile.getAbsolutePath());
    } finally {
        // 最后，无论是否成功生成文件，都确保临时文件被删除
        if (file != null && file.exists()) {
            file.delete();  // 删除临时文件
        }
    }
}

这个方法是文档导出的主要入口，主要实现了以下功能：

• 加载指定的FreeMarker模版
• 调用createDoc方法生成临时文档文件
• 确保输出目录存在
• 将临时文件重命名并移动到指定的输出位置
• 使用finally块确保临时文件被删除，无论过程是否成功

5.createDoc方法

这个方法是创建文档的核心方法，主要是通过创建一个临时文件，使用指定的FreeMarker模版和数据模型将内容填充到文件中，并确保文件使用UTF-8编码进行写入。该方法在执行过程中捕获异常并打印堆栈信息，确保发生错误时能够正确处理。最后。方法返回生成的文件对象，以便后续操作或保存。

// 创建文档的方法，使用 FreeMarker 模板生成内容并写入文件
private static File createDoc(Map dataMap, Template template, String name) {
    // 创建一个新的 File 对象，表示生成的文档文件，文件名由参数 "name" 提供
    File f = new File(name);
    
    try {
        // 使用 OutputStreamWriter 创建一个写入文件的 Writer 对象，设置编码为 "utf-8"
        Writer w = new OutputStreamWriter(new FileOutputStream(f), "utf-8");
        
        // 使用 FreeMarker 模板将数据填充到文件中
        template.process(dataMap, w);
        
        // 关闭 Writer，确保所有内容写入文件
        w.close();
    } catch (Exception ex) {
        // 捕获异常并打印错误堆栈信息
        ex.printStackTrace();
        
        // 抛出 RuntimeException，确保错误被传播到调用者
        throw new RuntimeException(ex);
    }
    
    // 返回生成的文件对象
    return f;
}

这个方法是实际创建文档的核心，主要实现以下功能：

• 创建一个临时文件。

• 使用OutputStreamWriter设置UTF-8编码,确保正确处理所有字符。

• 调用FreeMarker的template.process()方法,将数据模型(dataMap)应用到模板上。

• 关闭写入器。

• 如果过程中发生异常,打印堆栈跟踪并抛出RuntimeException。

• 返回生成的文件对象。

6.WordUtil类总结

WordUtil 类通过封装 FreeMarker 模板引擎的配置和文件操作，提供了一个简洁的文档生成工具。它加载指定模板，使用数据模型填充内容，创建临时文件，并确保文件按照指定路径保存。该类通过静态方法确保全局共享功能，使用 UTF-8 编码处理字符，捕获异常并清理临时文件，确保文档生成过程的稳定性和高效性。

FreeMarker模板深度解析

FreeMarker模板是整个文档生成过程的核心，它定义了最终Word文档的结构和样式。让我们来逐步分析模板的主要组成部分

1.文档结构和样式

 


    
    
    
    
    


    
    
${company}送货清单
    

这段代码通过HTML和内嵌CSS定义了页面布局和样式：

动态公司名称：