src
└── main
    ├── java
    │   └── com.example.demo
    │       ├── controller
    │       │   └── ContractController.java  <-- 接口類(lèi)（接收請(qǐng)求、調(diào)用工具類(lèi)）
    │       ├── dto
    │       │   ├── ContractDTO.java        <-- 主數(shù)據(jù)模型（對(duì)應(yīng)模板占位符）
    │       │   └── ContractDetailDTO.java  <-- 明細(xì)數(shù)據(jù)模型（對(duì)應(yīng)表格占位符）
    │       ├── util
    │       │   └── WordGenerateUtil.java   <-- 通用工具類(lèi)（封裝生成、下載邏輯）
    │       └── DemoApplication.java        <-- 項(xiàng)目啟動(dòng)類(lèi)
    └── resources
        ├── static
        │   └── img
        │       └── attachment.jpg          <-- 測(cè)試圖片（用于圖片渲染驗(yàn)證）
        ├── templates
        │   └── contractTemplate.docx       <-- Word模板（存放占位符）
        └── application.yml                 <-- 項(xiàng)目配置文件（默認(rèn)配置即可）

<!-- 核心依賴(lài)：實(shí)現(xiàn)Word模板渲染與生成 -->
<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl</artifactId>
    <version>1.12.2</version> 
</dependency>
<!-- Apache POI: 處理Office文檔的核心庫(kù) -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.5.1</version>
</dependency>
<!-- 可選但推薦：文件操作工具 -->
<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.21.0</version>
</dependency>

客戶(hù)合同
合同編號(hào)：{{contractNo}}
客戶(hù)姓名：{{customerName}}
聯(lián)系電話(huà)：{{phone}}
簽訂日期：{{signDate}}
合同明細(xì)：
{{#detailList}}
合同附件：{{@attachmentImg}}

import lombok.Data;
import java.util.List;
import java.math.BigDecimal;
/**
 * 合同主數(shù)據(jù)模型（對(duì)應(yīng)模板中的普通文本占位符）
 */
@Data
public class ContractDTO {
    // 合同編號(hào)（對(duì)應(yīng){{contractNo}}）
    private String contractNo;
    // 客戶(hù)姓名（對(duì)應(yīng){{customerName}}）
    private String customerName;
    // 聯(lián)系電話(huà)（對(duì)應(yīng){{phone}}）
    private String phone;
    // 簽訂日期（對(duì)應(yīng){{signDate}}）
    private String signDate;
    // 合同明細(xì)（對(duì)應(yīng){{#detailList}}循環(huán)表格）
    private List<ContractDetailDTO> detailList;
    // 附件圖片（對(duì)應(yīng){{@attachmentImg}}，無(wú)需賦值，接口中單獨(dú)處理）
    private String attachmentImg;
}
/**
 * 合同明細(xì)數(shù)據(jù)模型（對(duì)應(yīng)表格中的占位符）
 */
@Data
public class ContractDetailDTO {
    // 商品名稱(chēng)（對(duì)應(yīng){{productName}}）
    private String productName;
    // 單價(jià)（對(duì)應(yīng){{price}}）
    private BigDecimal price;
    // 數(shù)量（對(duì)應(yīng){{num}}）
    private Integer num;
    // 小計(jì)（對(duì)應(yīng){{total}}）
    private BigDecimal total;
}

import com.deepoove.poi.XWPFTemplate;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URLEncoder;
import java.util.Map;
/**
 * Word文檔生成工具類(lèi)（通用，可直接復(fù)用）
 */
@Component
public class WordGenerateUtil {
    /**
     * 生成Word并通過(guò)瀏覽器下載
     * @param templateName 模板文件名（放在resources/templates目錄下）
     * @param data 填充到模板的數(shù)據(jù)（Map格式，key對(duì)應(yīng)模板占位符）
     * @param response 響應(yīng)對(duì)象（用于返回下載流）
     * @param downloadFileName 下載時(shí)的文件名（如：張三的合同.docx）
     * @throws IOException 異常（可在調(diào)用處統(tǒng)一處理）
     */
    public void generateAndDownload(String templateName, Map<String, Object> data,
                                    HttpServletResponse response, String downloadFileName) throws IOException {
        // 1. 讀取templates目錄下的Word模板
        ClassPathResource resource = new ClassPathResource("templates/" + templateName);
        // 2. 編譯模板并填充數(shù)據(jù)
        XWPFTemplate template = XWPFTemplate.compile(resource.getInputStream()).render(data);
        // 3. 設(shè)置響應(yīng)頭，實(shí)現(xiàn)瀏覽器下載（解決中文文件名亂碼問(wèn)題）
        response.setContentType("application/vnd.openxmlformats-officedocument.wordprocessingml.document");
        response.setHeader("Content-Disposition", "attachment;filename=" + URLEncoder.encode(downloadFileName, "UTF-8"));
        response.setCharacterEncoding("UTF-8");
        // 4. 寫(xiě)入響應(yīng)流，完成下載
        try (OutputStream outputStream = response.getOutputStream()) {
            template.write(outputStream);
            outputStream.flush();
        } finally {
            // 5. 關(guān)閉資源，避免內(nèi)存泄漏
            template.close();
        }
    }
    /**
     * 生成Word并保存到本地（可選，根據(jù)需求使用）
     * @param templateName 模板文件名
     * @param data 填充數(shù)據(jù)
     * @param localPath 本地保存路徑（如：D:/contract/張三的合同.docx）
     * @throws IOException 異常
     */
    public void generateToLocal(String templateName, Map<String, Object> data, String localPath) throws IOException {
        ClassPathResource resource = new ClassPathResource("templates/" + templateName);
        XWPFTemplate template = XWPFTemplate.compile(resource.getInputStream()).render(data);
        // 寫(xiě)入本地文件
        template.writeToFile(localPath);
        template.close();
    }
}

import cn.iocoder.boot.entity.ContractDTO;
import cn.iocoder.boot.entity.ContractDetailDTO;
import cn.iocoder.boot.utils.WordGenerateUtil;
import com.deepoove.poi.data.*;
import jakarta.annotation.Resource;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.core.io.ClassPathResource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;
import java.math.BigDecimal;
import java.util.*;
/**
 * 合同導(dǎo)出接口（實(shí)戰(zhàn)示例）
 */
@RestController
@RequestMapping("/contract")
public class ContractController {
    @Resource
    private WordGenerateUtil wordGenerateUtil;
    /**
     * 導(dǎo)出單個(gè)客戶(hù)合同
     * @param customerId 客戶(hù)ID（實(shí)際開(kāi)發(fā)中用于查詢(xún)客戶(hù)數(shù)據(jù)）
     * @param response 響應(yīng)對(duì)象（返回下載流）
     * @throws IOException 異常
     */
    @GetMapping("/export/{customerId}")
    public void exportContract(@PathVariable String customerId, HttpServletResponse response) throws IOException {
        // 1. 模擬從數(shù)據(jù)庫(kù)查詢(xún)客戶(hù)合同數(shù)據(jù)（實(shí)際開(kāi)發(fā)中替換為真實(shí)DAO查詢(xún)）
        ContractDTO contractDTO = getContractData(customerId);
        // 2. 組裝數(shù)據(jù)（key必須和模板占位符完全一致）
        Map<String, Object> data = new HashMap<>();
        data.put("contractNo", contractDTO.getContractNo());
        data.put("customerName", contractDTO.getCustomerName());
        data.put("phone", contractDTO.getPhone());
        data.put("signDate", contractDTO.getSignDate());
        // 3. 創(chuàng)建表格數(shù)據(jù)
        RowRenderData row0 = Rows.of("商品名稱(chēng)", "單價(jià)（元）","數(shù)量","小計(jì)（元）").textColor("FFFFFF")
                .bgColor("4472C4").center().create();
        Tables.TableBuilder tableBuilder = Tables.of(row0);
        contractDTO.getDetailList().forEach(detail -> {
            RowRenderData row = Rows.create(detail.getProductName(), detail.getPrice().toString(), detail.getNum().toString(), detail.getTotal().toString());
            tableBuilder.addRow(row);
        });
        data.put("detailList", tableBuilder.create());
        // 4. 填充圖片，圖片路徑：項(xiàng)目resources/static/img目錄下的圖片（實(shí)際可從數(shù)據(jù)庫(kù)獲取圖片路徑）
        data.put("attachmentImg", Pictures.ofStream(
                        new ClassPathResource("static/img/attachment.jpg").getInputStream(), // 圖片流
                        PictureType.JPEG) // 圖片格式，無(wú)需手動(dòng)寫(xiě)后綴
                .size(200, 100) // 圖片寬高（單位：像素）
                .create()
        );
        // 5. 調(diào)用工具類(lèi)，生成并下載Word
        wordGenerateUtil.generateAndDownload(
                "contractTemplate.docx", // 模板文件名
                data, // 填充數(shù)據(jù)
                response, // 響應(yīng)對(duì)象
                contractDTO.getCustomerName() + "的合同.docx" // 下載文件名
        );
    }
    /**
     * 模擬查詢(xún)合同數(shù)據(jù)（實(shí)際開(kāi)發(fā)中替換為真實(shí)業(yè)務(wù)邏輯/DAO查詢(xún)）
     */
    private ContractDTO getContractData(String customerId) {
        ContractDTO contract = new ContractDTO();
        // 模擬主數(shù)據(jù)（實(shí)際從數(shù)據(jù)庫(kù)查詢(xún)）
        contract.setContractNo("HT-" + System.currentTimeMillis());
        contract.setCustomerName("張三");
        contract.setPhone("13800138000");
        contract.setSignDate("2026-03-25");
        // 模擬合同明細(xì)數(shù)據(jù)（對(duì)應(yīng)表格循環(huán)）
        List<ContractDetailDTO> detailList = new ArrayList<>();
        ContractDetailDTO detail1 = new ContractDetailDTO();
        detail1.setProductName("Java開(kāi)發(fā)服務(wù)");
        detail1.setPrice(new BigDecimal("5000.00"));
        detail1.setNum(1);
        detail1.setTotal(new BigDecimal("5000.00"));
        ContractDetailDTO detail2 = new ContractDetailDTO();
        detail2.setProductName("系統(tǒng)維護(hù)服務(wù)");
        detail2.setPrice(new BigDecimal("2000.00"));
        detail2.setNum(1);
        detail2.setTotal(new BigDecimal("2000.00"));
        detailList.add(detail1);
        detailList.add(detail2);
        contract.setDetailList(detailList);
        return contract;
    }
}